Feature: use hishel always revalidate option by default

githubkit/cache/base.py

@@ -4,6 +4,8 @@
 
 from hishel import AsyncBaseStorage, BaseStorage, Controller
 
+from githubkit.typing import HishelControllerOptions
+
 
 class BaseCache(abc.ABC):
     @abc.abstractmethod
@@ -42,12 +44,18 @@ def get_async_cache_storage(self) -> AsyncBaseCache:
         """
         raise NotImplementedError
 
-    def get_hishel_controller(self) -> Optional[Controller]:
+    def get_hishel_controller_options(self) -> HishelControllerOptions:
+        """Get the hishel controller options"""
+        # set always revalidate by default
+        # See: https://hishel.com/examples/github/
+        return HishelControllerOptions(always_revalidate=True)
+
+    def get_hishel_controller(self) -> Controller:
         """Get the hishel controller instance
 
-        Return `None` to use the default controller
+        Get the controller options from `get_hishel_controller_options` method
         """
-        return None
+        return Controller(**self.get_hishel_controller_options())
 
     @abc.abstractmethod
     def get_hishel_storage(self) -> BaseStorage:

githubkit/cache/redis.py

@@ -3,9 +3,10 @@
 from typing import TYPE_CHECKING, Any, NoReturn, Optional
 from typing_extensions import override
 
-from hishel import AsyncBaseStorage, AsyncRedisStorage, Controller, RedisStorage
+from hishel import AsyncBaseStorage, AsyncRedisStorage, RedisStorage
 
 from githubkit.exception import CacheUnsupportedError
+from githubkit.typing import HishelControllerOptions
 from githubkit.utils import hishel_key_generator_with_prefix
 
 from .base import AsyncBaseCache, BaseCache, BaseCacheStrategy
@@ -82,14 +83,16 @@ def get_async_cache_storage(self) -> NoReturn:
         )
 
     @override
-    def get_hishel_controller(self) -> Optional[Controller]:
+    def get_hishel_controller_options(self) -> HishelControllerOptions:
+        options = super().get_hishel_controller_options()
+
         if self.prefix is not None:
-            return Controller(
-                key_generator=partial(
-                    hishel_key_generator_with_prefix, prefix=self.prefix
-                )
+            options["key_generator"] = partial(
+                hishel_key_generator_with_prefix, prefix=self.prefix
             )
 
+        return options
+
     @override
     def get_hishel_storage(self) -> RedisStorage:
         return RedisStorage(client=self.client)

githubkit/typing.py

@@ -2,23 +2,29 @@
 from datetime import timedelta
 from typing import (
     IO,
+    TYPE_CHECKING,
     Annotated,
     Callable,
     Literal,
     NamedTuple,
     Optional,
+    TypedDict,
     TypeVar,
     Union,
 )
 from typing_extensions import TypeAlias
 
+import httpcore
 import httpx
 from pydantic import Field
 
 from .compat import PYDANTIC_V2
 from .exception import GitHubException
 from .utils import Unset
 
+if TYPE_CHECKING:
+    from hishel._utils import BaseClock
+
 T = TypeVar("T")
 H = TypeVar("H", bound=Hashable)
 
@@ -89,3 +95,17 @@ class RetryOption(NamedTuple):
 
 
 RetryDecisionFunc: TypeAlias = Callable[[GitHubException, int], RetryOption]
+
+
+class HishelControllerOptions(TypedDict, total=False):
+    """Options for the hishel controller."""
+
+    cacheable_methods: Optional[list[str]]
+    cacheable_status_codes: Optional[list[int]]
+    cache_private: bool
+    allow_heuristics: bool
+    clock: Optional["BaseClock"]
+    allow_stale: bool
+    always_revalidate: bool
+    force_cache: bool
+    key_generator: Optional[Callable[[httpcore.Request, Optional[bytes]], str]]