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

hishel/__init__.py

@@ -1,8 +1,7 @@
-from hishel._core._async._storages._sqlite import AsyncSqliteStorage
-from hishel._core._base._storages._base import (
-    AsyncBaseStorage as AsyncBaseStorage,
-    SyncBaseStorage as SyncBaseStorage,
-)
+from hishel._core._storages._async_sqlite import AsyncSqliteStorage
+from hishel._core._storages._async_base import AsyncBaseStorage
+from hishel._core._storages._sync_sqlite import SyncSqliteStorage
+from hishel._core._storages._sync_base import SyncBaseStorage
 from hishel._core._headers import Headers as Headers
 from hishel._core._spec import (
     AnyState as AnyState,
@@ -11,21 +10,24 @@ from hishel._core._spec import (
     CouldNotBeStored as CouldNotBeStored,
     FromCache as FromCache,
     IdleClient as IdleClient,
+    InvalidateEntries,
     NeedRevalidation as NeedRevalidation,
     NeedToBeUpdated as NeedToBeUpdated,
     State as State,
     StoreAndUse as StoreAndUse,
-    create_idle_state as create_idle_state,
 )
-from hishel._core._sync._storages._sqlite import SyncSqliteStorage
 from hishel._core.models import (
-    CompletePair as CompletePair,
-    IncompletePair as IncompletePair,
-    Pair as Pair,
-    PairMeta as PairMeta,
+    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
@@ -41,14 +43,14 @@ __all__ = (
     "State",
     "StoreAndUse",
     "CouldNotBeStored",
-    "create_idle_state",
+    "InvalidateEntries",
     ## Models
     "Request",
     "Response",
-    "Pair",
-    "IncompletePair",
-    "CompletePair",
-    "PairMeta",
+    "Entry",
+    "EntryMeta",
+    "RequestMetadata",
+    "ResponseMetadata",
     ## Headers
     "Headers",
     ## Storages
@@ -56,4 +58,11 @@ __all__ = (
     "AsyncBaseStorage",
     "SyncSqliteStorage",
     "AsyncSqliteStorage",
+    # Proxy
+    "AsyncCacheProxy",
+    "SyncCacheProxy",
+    # Policies
+    "CachePolicy",
+    "SpecificationPolicy",
+    "FilterPolicy",
 )

hishel/_async_cache.py

@@ -4,7 +4,7 @@ import hashlib
 import logging
 import time
 from dataclasses import replace
-from typing import AsyncIterator, Awaitable, Callable
+from typing import AsyncIterable, AsyncIterator, Awaitable, Callable
 
 from typing_extensions import assert_never
 
@@ -13,7 +13,6 @@ from hishel import (
     AsyncBaseStorage,
     AsyncSqliteStorage,
     CacheMiss,
-    CacheOptions,
     CouldNotBeStored,
     FromCache,
     IdleClient,
@@ -22,10 +21,11 @@ from hishel import (
     Request,
     Response,
     StoreAndUse,
-    create_idle_state,
 )
-from hishel._core._spec import InvalidatePairs, vary_headers_match
-from hishel._core.models import CompletePair, ResponseMetadata
+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")
 
@@ -36,84 +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,
-        send_request: Callable[[Request], Awaitable[Response]],
+        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 = send_request
+        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"):
-            assert isinstance(request.stream, AsyncIterator)
+        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()
-            return f"{str(request.url)}-{hash_}"
-        return str(request.url)
-
-    async def _maybe_refresh_pair_ttl(self, pair: CompletePair) -> None:
-        if pair.request.metadata.get("hishel_refresh_ttl_on_access"):
-            await self.storage.update_pair(
-                pair.id,
-                lambda complete_pair: replace(complete_pair, meta=replace(complete_pair.meta, created_at=time.time())),
+            request.stream = make_async_iterator([collected])
+            return hash_
+        return hashlib.sha256(str(request.url).encode("utf-8")).hexdigest()
+
+    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(
+                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")
-        pairs = await self.storage.get_pairs(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(pairs)} cached pairs for the request")
+        logger.debug(f"Found {len(entries)} cached entries for the request")
 
-        for pair in pairs:
+        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
-
-        incomplete_pair = await self.storage.create_pair(
-            request,
+                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 = await self.send_request(incomplete_pair.request)
+        response.metadata.update(response_meta)  # type: ignore
 
         logger.debug("Storing response in cache ignoring specification")
-        complete_pair = await self.storage.add_response(
-            incomplete_pair.id, response, await self._get_key_for_request(request)
+        entry = await self.storage.create_entry(
+            request,
+            response,
+            cache_key,
         )
-        return complete_pair.response
+        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__}")
@@ -128,47 +165,49 @@ 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, InvalidatePairs):
-                state = await self._handle_invalidate_pairs(state)
+            elif isinstance(state, InvalidateEntries):
+                state = await self._handle_invalidate_entries(state)
             else:
                 assert_never(state)
 
         raise RuntimeError("Unreachable")
 
     async def _handle_idle_state(self, state: IdleClient, request: Request) -> AnyState:
-        stored_pairs = await self.storage.get_pairs(await self._get_key_for_request(request))
-        return state.next(request, stored_pairs)
+        stored_entries = await self.storage.get_entries(await self._get_key_for_request(request))
+        return state.next(request, stored_entries)
 
     async def _handle_cache_miss(self, state: CacheMiss) -> AnyState:
-        incomplete_pair = await self.storage.create_pair(state.request)
-        response = await self.send_request(incomplete_pair.request)
-        return state.next(response, incomplete_pair.id)
+        response = await self.send_request(state.request)
+        return state.next(response)
 
     async def _handle_store_and_use(self, state: StoreAndUse, request: Request) -> Response:
-        complete_pair = await self.storage.add_response(
-            state.pair_id, state.response, await self._get_key_for_request(request)
+        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)
         return state.next(revalidation_response)
 
     async def _handle_update(self, state: NeedToBeUpdated) -> AnyState:
-        for pair in state.updating_pairs:
-            await self.storage.update_pair(
-                pair.id,
-                lambda complete_pair: replace(
-                    complete_pair, response=replace(pair.response, headers=pair.response.headers)
+        for entry in state.updating_entries:
+            await self.storage.update_entry(
+                entry.id,
+                lambda entry: replace(
+                    entry,
+                    response=replace(entry.response, headers=entry.response.headers),
                 ),
             )
         return state.next()
 
-    async def _handle_invalidate_pairs(self, state: InvalidatePairs) -> AnyState:
-        for pair_id in state.pair_ids:
-            await self.storage.remove(pair_id)
+    async def _handle_invalidate_entries(self, state: InvalidateEntries) -> AnyState:
+        for entry_id in state.entry_ids:
+            await self.storage.remove_entry(entry_id)
         return state.next()

hishel/_async_httpx.py

@@ -0,0 +1,236 @@
+from __future__ import annotations
+
+import ssl
+import typing as t
+from typing import (
+    AsyncIterable,
+    AsyncIterator,
+    Iterator,
+    Union,
+    cast,
+    overload,
+)
+
+from httpx import RequestNotRead
+
+from hishel import AsyncCacheProxy, Headers, Request, Response
+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,
+)
+
+try:
+    import httpx
+except ImportError as e:
+    raise ImportError(
+        "httpx is required to use hishel.httpx module. "
+        "Please install hishel with the 'httpx' extra, "
+        "e.g., 'pip install hishel[httpx]'."
+    ) from e
+
+SOCKET_OPTION = t.Union[
+    t.Tuple[int, int, int],
+    t.Tuple[int, int, t.Union[bytes, bytearray]],
+    t.Tuple[int, int, None, int],
+]
+
+# 128 KB
+CHUNK_SIZE = 131072
+
+
+@overload
+def _internal_to_httpx(
+    value: Request,
+) -> httpx.Request: ...
+@overload
+def _internal_to_httpx(
+    value: Response,
+) -> httpx.Response: ...
+def _internal_to_httpx(
+    value: Union[Request, Response],
+) -> Union[httpx.Request, httpx.Response]:
+    """
+    Convert internal Request/Response to httpx.Request/httpx.Response.
+    """
+    if isinstance(value, Request):
+        return httpx.Request(
+            method=value.method,
+            url=value.url,
+            headers=value.headers,
+            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()),
+            extensions=value.metadata,
+        )
+
+
+@overload
+def _httpx_to_internal(
+    value: httpx.Request,
+) -> Request: ...
+@overload
+def _httpx_to_internal(
+    value: httpx.Response,
+) -> Response: ...
+def _httpx_to_internal(
+    value: Union[httpx.Request, httpx.Response],
+) -> Union[Request, Response]:
+    """
+    Convert httpx.Request/httpx.Response to internal Request/Response.
+    """
+    headers = Headers(
+        filter_mapping(
+            Headers({key: value for key, value in value.headers.items()}),
+            ["Transfer-Encoding"],
+        )
+    )
+    if isinstance(value, httpx.Request):
+        extension_metadata = RequestMetadata(
+            hishel_refresh_ttl_on_access=value.extensions.get("hishel_refresh_ttl_on_access"),
+            hishel_ttl=value.extensions.get("hishel_ttl"),
+            hishel_spec_ignore=value.extensions.get("hishel_spec_ignore"),
+            hishel_body_key=value.extensions.get("hishel_body_key"),
+        )
+        headers_metadata = extract_metadata_from_headers(value.headers)
+
+        for key, val in extension_metadata.items():
+            if key in value.extensions:
+                headers_metadata[key] = val  # type: ignore
+
+        try:
+            stream = make_async_iterator([value.content])
+        except RequestNotRead:
+            stream = cast(AsyncIterator[bytes], value.stream)
+
+        return Request(
+            method=value.method,
+            url=str(value.url),
+            headers=headers,
+            stream=stream,
+            metadata=headers_metadata,
+        )
+    elif isinstance(value, httpx.Response):
+        if value.is_stream_consumed and "content-encoding" in value.headers:
+            raise RuntimeError("Can't get the raw stream of a response with `Content-Encoding` header.")
+        stream = (
+            make_async_iterator([value.content]) if value.is_stream_consumed else value.aiter_raw(chunk_size=CHUNK_SIZE)
+        )
+
+        return Response(
+            status_code=value.status_code,
+            headers=headers,
+            stream=stream,
+            metadata={},
+        )
+
+
+class _IteratorStream(httpx.SyncByteStream, httpx.AsyncByteStream):
+    def __init__(self, iterator: Iterator[bytes] | AsyncIterator[bytes]) -> None:
+        self.iterator = iterator
+
+    async def __aiter__(self) -> AsyncIterator[bytes]:
+        assert isinstance(self.iterator, (AsyncIterator, AsyncIterable))
+        async for chunk in self.iterator:
+            yield chunk
+
+
+class AsyncCacheTransport(httpx.AsyncBaseTransport):
+    def __init__(
+        self,
+        next_transport: httpx.AsyncBaseTransport,
+        storage: AsyncBaseStorage | None = None,
+        policy: CachePolicy | None = None,
+    ) -> None:
+        self.next_transport = next_transport
+        self._cache_proxy: AsyncCacheProxy = AsyncCacheProxy(
+            request_sender=self.request_sender,
+            storage=storage,
+            policy=policy,
+        )
+        self.storage = self._cache_proxy.storage
+
+    async def handle_async_request(
+        self,
+        request: httpx.Request,
+    ) -> httpx.Response:
+        internal_request = _httpx_to_internal(request)
+        internal_response = await self._cache_proxy.handle_request(internal_request)
+        response = _internal_to_httpx(internal_response)
+        return response
+
+    async def aclose(self) -> None:
+        await self.next_transport.aclose()
+        await self.storage.close()
+        await super().aclose()
+
+    async def request_sender(self, request: Request) -> Response:
+        httpx_request = _internal_to_httpx(request)
+        httpx_response = await self.next_transport.handle_async_request(httpx_request)
+        return _httpx_to_internal(httpx_response)
+
+
+class AsyncCacheClient(httpx.AsyncClient):
+    def __init__(self, *args: t.Any, **kwargs: t.Any) -> None:
+        self.storage: AsyncBaseStorage | None = kwargs.pop("storage", None)
+        self.policy: CachePolicy | None = kwargs.pop("policy", None)
+        super().__init__(*args, **kwargs)
+
+    def _init_transport(
+        self,
+        verify: ssl.SSLContext | str | bool = True,
+        cert: t.Union[str, t.Tuple[str, str], t.Tuple[str, str, str], None] = None,
+        trust_env: bool = True,
+        http1: bool = True,
+        http2: bool = False,
+        limits: httpx.Limits = httpx.Limits(max_connections=100, max_keepalive_connections=20),
+        transport: httpx.AsyncBaseTransport | None = None,
+        **kwargs: t.Any,
+    ) -> httpx.AsyncBaseTransport:
+        if transport is not None:
+            return transport
+
+        return AsyncCacheTransport(
+            next_transport=httpx.AsyncHTTPTransport(
+                verify=verify,
+                cert=cert,
+                trust_env=trust_env,
+                http1=http1,
+                http2=http2,
+                limits=limits,
+            ),
+            storage=self.storage,
+            policy=self.policy,
+        )
+
+    def _init_proxy_transport(
+        self,
+        proxy: httpx.Proxy,
+        verify: ssl.SSLContext | str | bool = True,
+        cert: t.Union[str, t.Tuple[str, str], t.Tuple[str, str, str], None] = None,
+        trust_env: bool = True,
+        http1: bool = True,
+        http2: bool = False,
+        limits: httpx.Limits = httpx.Limits(max_connections=100, max_keepalive_connections=20),
+        **kwargs: t.Any,
+    ) -> httpx.AsyncBaseTransport:
+        return AsyncCacheTransport(
+            next_transport=httpx.AsyncHTTPTransport(
+                verify=verify,
+                cert=cert,
+                trust_env=trust_env,
+                http1=http1,
+                http2=http2,
+                limits=limits,
+                proxy=proxy,
+            ),
+            storage=self.storage,
+            policy=self.policy,
+        )

hishel/_core/_headers.py

@@ -1,7 +1,17 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Any, Iterator, List, Literal, Mapping, MutableMapping, Optional, Union, cast
+from typing import (
+    Any,
+    Iterator,
+    List,
+    Literal,
+    Mapping,
+    MutableMapping,
+    Optional,
+    Union,
+    cast,
+)
 
 """
 HTTP token and quoted-string parsing utilities.