hishel 0.0.31__tar.gz → 0.0.33__tar.gz

{hishel-0.0.31 → hishel-0.0.33}/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.0.33 (4th Oct, 2024)
+
+- Added a [Logging](https://hishel.com/advanced/logging/) section to the documentation.
+
+## 0.0.32 (27th Sep, 2024)
+
+- Don't raise an exception if the `Date` header is not present. (#273)
+
 ## 0.0.31 (22nd Sep, 2024)
 
 - Ignore file not found error when cleaning up a file storage. (#264)  

{hishel-0.0.31 → hishel-0.0.33}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: hishel
-Version: 0.0.31
+Version: 0.0.33
 Summary: Persistent cache implementation for httpx and httpcore
 Project-URL: Homepage, https://hishel.com
 Project-URL: Source, https://github.com/karpetrosyan/hishel
@@ -175,6 +175,14 @@ Help us grow and continue developing good software for you ❤️
 
 # Changelog
 
+## 0.0.33 (4th Oct, 2024)
+
+- Added a [Logging](https://hishel.com/advanced/logging/) section to the documentation.
+
+## 0.0.32 (27th Sep, 2024)
+
+- Don't raise an exception if the `Date` header is not present. (#273)
+
 ## 0.0.31 (22nd Sep, 2024)
 
 - Ignore file not found error when cleaning up a file storage. (#264)  

{hishel-0.0.31 → hishel-0.0.33}/hishel/__init__.py

@@ -14,4 +14,4 @@ def install_cache() -> None:  # pragma: no cover
     httpx.Client = CacheClient  # type: ignore
 
 
-__version__ = "0.0.31"
+__version__ = "0.0.33"

{hishel-0.0.31 → hishel-0.0.33}/hishel/_controller.py

@@ -1,3 +1,4 @@
+import logging
 import typing as tp
 
 from httpcore import Request, Response
@@ -10,10 +11,13 @@ from ._utils import (
     extract_header_values,
     extract_header_values_decoded,
     generate_key,
+    get_safe_url,
     header_presents,
     parse_date,
 )
 
+logger = logging.getLogger("hishel.controller")
+
 HEURISTICALLY_CACHEABLE_STATUS_CODES = (200, 203, 204, 206, 300, 301, 308, 404, 405, 410, 414, 501)
 HTTP_METHODS = ["GET", "HEAD", "POST", "PUT", "DELETE", "CONNECT", "OPTIONS", "TRACE", "PATCH"]
 
@@ -79,8 +83,10 @@ def get_heuristic_freshness(response: Response, clock: "BaseClock") -> int:
 
 
 def get_age(response: Response, clock: "BaseClock") -> int:
-    if not header_presents(response.headers, b"date"):  # pragma: no cover
-        raise RuntimeError("The `Date` header is missing in the response.")
+    if not header_presents(response.headers, b"date"):
+        # If the response does not have a date header, then it is impossible to calculate the age.
+        # Instead of raising an exception, we return infinity to be sure that the response is not considered fresh.
+        return float("inf")  # type: ignore
 
     date = parse_date(extract_header_values_decoded(response.headers, b"date")[0])
 
@@ -150,16 +156,41 @@ class Controller:
         force_cache = request.extensions.get("force_cache", None)
 
         if response.status not in self._cacheable_status_codes:
+            logger.debug(
+                (
+                    f"Considering the resource located at {get_safe_url(request.url)} "
+                    f"as not cachable since its status code ({response.status})"
+                    " is not in the list of cacheable status codes."
+                )
+            )
             return False
 
         if response.status in (301, 308):
+            logger.debug(
+                (
+                    f"Considering the resource located at {get_safe_url(request.url)} "
+                    "as cachable since its status code is a permanent redirect."
+                )
+            )
             return True
 
         # the request method is understood by the cache
         if method not in self._cacheable_methods:
+            logger.debug(
+                (
+                    f"Considering the resource located at {get_safe_url(request.url)} "
+                    f"as not cachable since the request method ({method}) is not in the list of cacheable methods."
+                )
+            )
             return False
 
         if force_cache if force_cache is not None else self._force_cache:
+            logger.debug(
+                (
+                    f"Considering the resource located at {get_safe_url(request.url)} "
+                    "as cachable since the request is forced to use the cache."
+                )
+            )
             return True
 
         response_cache_control = parse_cache_control(extract_header_values_decoded(response.headers, b"cache-control"))
@@ -167,21 +198,53 @@ class Controller:
 
         # the response status code is final
         if response.status // 100 == 1:
+            logger.debug(
+                (
+                    f"Considering the resource located at {get_safe_url(request.url)} "
+                    "as not cachable since its status code is informational."
+                )
+            )
             return False
 
         # the no-store cache directive is not present (see Section 5.2.2.5)
         if request_cache_control.no_store:
+            logger.debug(
+                (
+                    f"Considering the resource located at {get_safe_url(request.url)} "
+                    "as not cachable since the request contains the no-store directive."
+                )
+            )
             return False
 
         # note that the must-understand cache directive overrides
         # no-store in certain circumstances; see Section 5.2.2.3.
-        if response_cache_control.no_store and not response_cache_control.must_understand:
-            return False
+        if response_cache_control.no_store:
+            if response_cache_control.must_understand:
+                logger.debug(
+                    (
+                        f"Skipping the no-store directive for the resource located at {get_safe_url(request.url)} "
+                        "since the response contains the must-understand directive."
+                    )
+                )
+            else:
+                logger.debug(
+                    (
+                        f"Considering the resource located at {get_safe_url(request.url)} "
+                        "as not cachable since the response contains the no-store directive."
+                    )
+                )
+                return False
 
         # a shared cache must not store a response with private directive
         # Note that we do not implement special handling for the qualified form,
         # which would only forbid storing specified headers.
         if not self._cache_private and response_cache_control.private:
+            logger.debug(
+                (
+                    f"Considering the resource located at {get_safe_url(request.url)} "
+                    "as not cachable since the response contains the private directive."
+                )
+            )
             return False
 
         expires_presents = header_presents(response.headers, b"expires")
@@ -194,6 +257,12 @@ class Controller:
         # - a cache extension that allows it to be cached (see Section 5.2.3); or
         # - a status code that is defined as heuristically cacheable (see Section 4.2.2).
         if self._allow_heuristics and response.status in HEURISTICALLY_CACHEABLE_STATUS_CODES:
+            logger.debug(
+                (
+                    f"Considering the resource located at {get_safe_url(request.url)} "
+                    "as cachable since its status code is heuristically cacheable."
+                )
+            )
             return True
 
         if not any(
@@ -204,8 +273,20 @@ class Controller:
                 response_cache_control.max_age is not None,
             ]
         ):
+            logger.debug(
+                (
+                    f"Considering the resource located at {get_safe_url(request.url)} "
+                    "as not cachable since it does not contain any of the required cache directives."
+                )
+            )
             return False
 
+        logger.debug(
+            (
+                f"Considering the resource located at {get_safe_url(request.url)} "
+                "as cachable since it meets the criteria for being stored in the cache."
+            )
+        )
         # response is a cachable!
         return True
 
@@ -221,11 +302,23 @@ class Controller:
 
         if header_presents(response.headers, b"last-modified"):
             last_modified = extract_header_values(response.headers, b"last-modified", single=True)[0]
+            logger.debug(
+                (
+                    f"Adding the 'If-Modified-Since' header with the value of '{last_modified.decode('ascii')}' "
+                    f"to the request for the resource located at {get_safe_url(request.url)}."
+                )
+            )
         else:
             last_modified = None
 
         if header_presents(response.headers, b"etag"):
             etag = extract_header_values(response.headers, b"etag", single=True)[0]
+            logger.debug(
+                (
+                    f"Adding the 'If-None-Match' header with the value of '{etag.decode('ascii')}' "
+                    f"to the request for the resource located at {get_safe_url(request.url)}."
+                )
+            )
         else:
             etag = None
 
@@ -278,6 +371,12 @@ class Controller:
         # Use of responses with status codes 301 and 308 is always
         # legal as long as they don't adhere to any caching rules.
         if response.status in (301, 308):
+            logger.debug(
+                (
+                    f"Considering the resource located at {get_safe_url(request.url)} "
+                    "as valid for cache use since its status code is a permanent redirect."
+                )
+            )
             return response
 
         response_cache_control = parse_cache_control(extract_header_values_decoded(response.headers, b"Cache-Control"))
@@ -287,11 +386,23 @@ class Controller:
         # response (if any) match those presented (see Section 4.1)
         if not self._validate_vary(request=request, response=response, original_request=original_request):
             # If the vary headers does not match, then do not use the response
+            logger.debug(
+                (
+                    f"Considering the resource located at {get_safe_url(request.url)} "
+                    "as invalid for cache use since the vary headers do not match."
+                )
+            )
             return None  # pragma: no cover
 
         # !!! this should be after the "vary" header validation.
         force_cache = request.extensions.get("force_cache", None)
         if force_cache if force_cache is not None else self._force_cache:
+            logger.debug(
+                (
+                    f"Considering the resource located at {get_safe_url(request.url)} "
+                    "as valid for cache use since the request is forced to use the cache."
+                )
+            )
             return response
 
         # the stored response does not contain the
@@ -303,15 +414,58 @@ class Controller:
             or response_cache_control.must_revalidate
             or request_cache_control.no_cache
         ):
+            if self._always_revalidate:
+                log_text = (
+                    f"Considering the resource located at {get_safe_url(request.url)} "
+                    "as needing revalidation since the cache is set to always revalidate."
+                )
+            elif response_cache_control.no_cache:
+                log_text = (
+                    f"Considering the resource located at {get_safe_url(request.url)} "
+                    "as needing revalidation since the response contains the no-cache directive."
+                )
+            elif response_cache_control.must_revalidate:
+                log_text = (
+                    f"Considering the resource located at {get_safe_url(request.url)} "
+                    "as needing revalidation since the response contains the must-revalidate directive."
+                )
+            elif request_cache_control.no_cache:
+                log_text = (
+                    f"Considering the resource located at {get_safe_url(request.url)} "
+                    "as needing revalidation since the request contains the no-cache directive."
+                )
+            else:
+                assert False, "Unreachable code "  # pragma: no cover
+            logger.debug(log_text)
             self._make_request_conditional(request=request, response=response)
             return request
 
         freshness_lifetime = get_freshness_lifetime(response)
 
         if freshness_lifetime is None:
+            logger.debug(
+                (
+                    "Could not determine the freshness lifetime of "
+                    f"the resource located at {get_safe_url(request.url)}, "
+                    "trying to use heuristics to calculate it."
+                )
+            )
             if self._allow_heuristics and response.status in HEURISTICALLY_CACHEABLE_STATUS_CODES:
                 freshness_lifetime = get_heuristic_freshness(response=response, clock=self._clock)
+                logger.debug(
+                    (
+                        f"Successfully calculated the freshness lifetime of the resource located at "
+                        f"{get_safe_url(request.url)} using heuristics."
+                    )
+                )
             else:
+                logger.debug(
+                    (
+                        "Could not calculate the freshness lifetime of "
+                        f"the resource located at {get_safe_url(request.url)}. "
+                        "Making a conditional request to revalidate the response."
+                    )
+                )
                 # If Freshness cannot be calculated, then send the request
                 self._make_request_conditional(request=request, response=response)
                 return request
@@ -326,6 +480,13 @@ class Controller:
         # be fresh for at least the specified number of seconds.
         if request_cache_control.min_fresh is not None:
             if freshness_lifetime < (age + request_cache_control.min_fresh):
+                logger.debug(
+                    (
+                        f"Considering the resource located at {get_safe_url(request.url)} "
+                        "as invalid for cache use since the time left for "
+                        "freshness is less than the min-fresh directive."
+                    )
+                )
                 return None
 
         # The max-stale request directive indicates that the
@@ -338,7 +499,21 @@ class Controller:
             exceeded_freshness_lifetime = age - freshness_lifetime
 
             if request_cache_control.max_stale < exceeded_freshness_lifetime:
+                logger.debug(
+                    (
+                        f"Considering the resource located at {get_safe_url(request.url)} "
+                        "as invalid for cache use since the freshness lifetime has been exceeded more than max-stale."
+                    )
+                )
                 return None
+            else:
+                logger.debug(
+                    (
+                        f"Considering the resource located at {get_safe_url(request.url)} "
+                        "as valid for cache use since the freshness lifetime has been exceeded less than max-stale."
+                    )
+                )
+                return response
 
         # The max-age request directive indicates that
         # the client prefers a response whose age is
@@ -347,9 +522,12 @@ class Controller:
         # the client does not wish to receive a stale response.
         if request_cache_control.max_age is not None:
             if request_cache_control.max_age < age:
-                return None
-
-            if request_cache_control.max_stale is None and not is_fresh:
+                logger.debug(
+                    (
+                        f"Considering the resource located at {get_safe_url(request.url)} "
+                        "as invalid for cache use since the age of the response exceeds the max-age directive."
+                    )
+                )
                 return None
 
         # the stored response is one of the following:
@@ -357,8 +535,20 @@ class Controller:
         #   allowed to be served stale (see Section 4.2.4), or
         #   successfully validated (see Section 4.3).
         if is_fresh:
+            logger.debug(
+                (
+                    f"Considering the resource located at {get_safe_url(request.url)} "
+                    "as valid for cache use since it is fresh."
+                )
+            )
             return response
         else:
+            logger.debug(
+                (
+                    f"Considering the resource located at {get_safe_url(request.url)} "
+                    "as needing revalidation since it is not fresh."
+                )
+            )
             # Otherwise, make a conditional request
             self._make_request_conditional(request=request, response=response)
             return request

{hishel-0.0.31 → hishel-0.0.33}/hishel/_utils.py

@@ -6,6 +6,7 @@ from hashlib import blake2b
 
 import anyio
 import httpcore
+import httpx
 
 HEADERS_ENCODING = "iso-8859-1"
 
@@ -33,6 +34,16 @@ def normalized_url(url: tp.Union[httpcore.URL, str, bytes]) -> str:
     assert False, "Invalid type for `normalized_url`"  # pragma: no cover
 
 
+def get_safe_url(url: httpcore.URL) -> str:
+    httpx_url = httpx.URL(bytes(url).decode("ascii"))
+
+    schema = httpx_url.scheme
+    host = httpx_url.host
+    path = httpx_url.path
+
+    return f"{schema}://{host}{path}"
+
+
 def generate_key(request: httpcore.Request, body: bytes = b"") -> str:
     encoded_url = normalized_url(request.url).encode("ascii")