From 7ea827f51c82403ee1f78b66d43433acc073aea8 Mon Sep 17 00:00:00 2001
From: Ju4tCode <42488585+yanyongyu@users.noreply.github.com>
Date: Mon, 23 Jun 2025 04:09:41 +0000
Subject: [PATCH] :sparkles: use hishel always revalidate option by default

---
 githubkit/cache/base.py  | 14 +++++++++++---
 githubkit/cache/redis.py | 15 +++++++++------
 githubkit/typing.py      | 20 ++++++++++++++++++++
 3 files changed, 40 insertions(+), 9 deletions(-)

diff --git a/githubkit/cache/base.py b/githubkit/cache/base.py
index be862dbc38..fe7c464617 100644
--- a/githubkit/cache/base.py
+++ b/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:
diff --git a/githubkit/cache/redis.py b/githubkit/cache/redis.py
index 78922e5e1e..7a20dec6e9 100644
--- a/githubkit/cache/redis.py
+++ b/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)
diff --git a/githubkit/typing.py b/githubkit/typing.py
index f9a9a0bcf2..afa07cbdb9 100644
--- a/githubkit/typing.py
+++ b/githubkit/typing.py
@@ -2,16 +2,19 @@
 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
 
@@ -19,6 +22,9 @@
 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]]