Merge branch 'feature/fixed_ttl_window' into develop

Author: tanbro

CHANGELOG.md

@@ -8,6 +8,7 @@
   - Added arguments excluding support for the `RedisFuncCache` class, which makes it possible to cache functions with arguments that cannot be serialized.
   - Added support for per-invocation TTL.
   - `RdisFuncCache.disabled()` provides a scope in which the cache is disabled temporarily.
+  - Added support for controlling cache TTL update behavior with `update_ttl` parameter.
 
 - 💔 **Breaking Changes:**
   - Rename `redis_func_cache.mixins.policies` to `redis_func_cache.mixins.scripts`.

README.md

@@ -464,6 +464,47 @@ Other serialization libraries such as [bson][], [simplejson](https://pypi.org/pr
 > The [`pickle`][] module is highly powerful but poses a significant security risk because it can execute arbitrary code during deserialization. Use it with extreme caution, especially when handling data from untrusted sources.
 > For best practices, it is recommended to cache functions that return simple, [JSON][]-serializable data. If you need to serialize more complex data structures than those supported by [JSON][], consider using safer alternatives such as [bson][], [msgpack][], or [yaml][].
 
+### TTL Update Behavior
+
+By default, accessing cached data updates the expiration time (TTL) of the cache data structures. This behavior is referred to as "sliding TTL". However, you can control this behavior using the `update_ttl` parameter.
+
+There are two TTL update modes:
+
+- **Sliding TTL** (`update_ttl=True`, default): Each cache access (both read and write) extends the life of the cache data structures.
+- **Fixed TTL** (`update_ttl=False`): The expiration time is set only when the cache data structures are first created, and subsequent accesses do not extend their life.
+
+You can set the `update_ttl` parameter at the cache instance level:
+
+```python
+# Sliding TTL (default behavior)
+sliding_cache = RedisFuncCache("sliding-cache", LruTPolicy, redis_client, update_ttl=True)
+
+# Fixed TTL
+fixed_cache = RedisFuncCache("fixed-cache", LruTPolicy, redis_client, update_ttl=False)
+```
+
+Or override it at the function level:
+
+```python
+cache = RedisFuncCache("my-cache", LruTPolicy, redis_client)
+
+# Override to use fixed TTL for this specific function
+@cache(update_ttl=False)
+def my_func(x):
+    ...
+
+# Override to use sliding TTL for this specific function
+@cache(update_ttl=True)
+def another_func(x):
+    ...
+```
+
+The `update_ttl` parameter controls the behavior of the cache data structures (sorted set and hash map) as a whole, not individual cached items. It is independent of the per-item TTL (set via the `ttl` parameter in the decorator), which controls the expiration of individual cached function results.
+
+> 💡 **Tip:** \
+> Use fixed TTL when you want predictable cache expiration behavior, regardless of how often cached functions are accessed.
+> Use sliding TTL when you want frequently accessed cached data to remain in cache longer.
+
 ## Advanced Usage
 
 ### Custom result serializer
@@ -657,7 +698,7 @@ The serializer and decoder are defined in the `__hash_config__` attribute of the
 
 This configuration can be illustrated as follows:
 
-```mermaid
+```
 flowchart TD
     A[Start] --> B{Is f callable?}
     B -->|No| C[Throw TypeError]
@@ -988,7 +1029,7 @@ pre-commit install
 
 ### Module structure
 
-```mermaid
+```
 graph TD
     A[RedisFuncCache] --> B[AbstractPolicy]
     A --> C[Serializer]
@@ -1016,7 +1057,7 @@ graph TD
 
 Core class:
 
-```mermaid
+```
 classDiagram
     class RedisFuncCache {
         -client: RedisClientTV
@@ -1059,7 +1100,7 @@ classDiagram
 
 Strategy pattern and mixins:
 
-```mermaid
+```
 classDiagram
     class LruPolicy {
         __key__ = "lru"
@@ -1091,7 +1132,7 @@ classDiagram
 
 Cluster and multiple-keys support
 
-```mermaid
+```
 classDiagram
     class BaseClusterSinglePolicy {
         +calc_keys(f, args, kwds) -> Tuple[str, str]
@@ -1113,7 +1154,7 @@ classDiagram
 
 Decorator and proxy:
 
-```mermaid
+```
 classDiagram
     class RedisFuncCache {
         +__call__(user_function) -> CallableTV
@@ -1130,7 +1171,7 @@ classDiagram
 
 Weak reference:
 
-```mermaid
+```
 classDiagram
     class AbstractPolicy {
         -_cache: CallableProxyType[RedisFuncCache]

src/redis_func_cache/cache.py

@@ -98,6 +98,7 @@ def __init__(
         client: Union[RedisClientTV, Callable[[], RedisClientTV]],
         maxsize: int = DEFAULT_MAXSIZE,
         ttl: int = DEFAULT_TTL,
+        update_ttl: bool = True,
         prefix: str = DEFAULT_PREFIX,
         serializer: SerializerSetterValueT = "json",
     ):
@@ -138,6 +139,12 @@ def __init__(
                 Zero or negative values means no set ttl.
                 Assigned to property :attr:`ttl`.
 
+            update_ttl: Whether to update the TTL of cached items when they are accessed.
+
+                If not provided, the default is ``True``.
+                When ``True``, accessing a cached item will reset its TTL.
+                When ``False``, accessing a cached item will not update its TTL.
+
             prefix: The prefix for cache keys.
 
                 If not provided, the default is :data:`.DEFAULT_PREFIX`.
@@ -186,6 +193,7 @@ def my_deserializer(data):
         self.prefix = prefix
         self.maxsize = maxsize
         self.ttl = ttl
+        self.update_ttl = update_ttl
         self._policy_type = policy
         self._policy_instance: Optional[AbstractPolicy] = None
         self._redis_instance: Optional[RedisClientTV] = None
@@ -368,6 +376,7 @@ def get(
         script: redis.commands.core.Script,
         key_pair: Tuple[KeyT, KeyT],
         hash_value: KeyT,
+        update_ttl: bool,
         ttl: int,
         options: Optional[Mapping[str, Any]] = None,
         ext_args: Optional[Iterable[EncodableT]] = None,
@@ -387,22 +396,23 @@ def get(
         """
         encoded_options = json.dumps(options or {}, ensure_ascii=False).encode()
         ext_args = ext_args or ()
-        return script(keys=key_pair, args=chain((ttl, hash_value, encoded_options), ext_args))
+        return script(keys=key_pair, args=chain((int(update_ttl), ttl, hash_value, encoded_options), ext_args))
 
     @classmethod
     async def aget(
         cls,
         script: redis.commands.core.AsyncScript,
         key_pair: Tuple[KeyT, KeyT],
         hash_: KeyT,
+        update_ttl: bool,
         ttl: int,
         options: Optional[Mapping[str, Any]] = None,
         ext_args: Optional[Iterable[EncodableT]] = None,
     ) -> Optional[EncodedT]:
         """Async version of :meth:`get`"""
         encoded_options = json.dumps(options or {}, ensure_ascii=False).encode()
         ext_args = ext_args or ()
-        return await script(keys=key_pair, args=chain((ttl, hash_, encoded_options), ext_args))
+        return await script(keys=key_pair, args=chain((int(update_ttl), ttl, hash_, encoded_options), ext_args))
 
     @classmethod
     def put(
@@ -412,6 +422,7 @@ def put(
         hash_value: KeyT,
         value: EncodableT,
         maxsize: int,
+        update_ttl: bool,
         ttl: int,
         field_ttl: int = 0,
         options: Optional[Mapping[str, Any]] = None,
@@ -433,7 +444,10 @@ def put(
         """
         encoded_options = json.dumps(options or {}, ensure_ascii=False).encode()
         ext_args = ext_args or ()
-        script(keys=key_pair, args=chain((maxsize, ttl, hash_value, value, field_ttl, encoded_options), ext_args))
+        script(
+            keys=key_pair,
+            args=chain((maxsize, int(update_ttl), ttl, hash_value, value, field_ttl, encoded_options), ext_args),
+        )
 
     @classmethod
     async def aput(
@@ -443,6 +457,7 @@ async def aput(
         hash_: KeyT,
         value: EncodableT,
         maxsize: int,
+        update_ttl: bool,
         ttl: int,
         field_ttl: int = 0,
         options: Optional[Mapping[str, Any]] = None,
@@ -451,7 +466,10 @@ async def aput(
         """Async version of :meth:`put`"""
         encoded_options = json.dumps(options or {}, ensure_ascii=False).encode()
         ext_args = ext_args or ()
-        await script(keys=key_pair, args=chain((maxsize, ttl, hash_, value, field_ttl, encoded_options), ext_args))
+        await script(
+            keys=key_pair,
+            args=chain((maxsize, int(update_ttl), ttl, hash_, value, field_ttl, encoded_options), ext_args),
+        )
 
     @classmethod
     def make_bound(
@@ -499,6 +517,7 @@ def exec(
         deserialize_func: Optional[DeserializerT] = None,
         bound: Optional[BoundArguments] = None,
         field_ttl: int = 0,
+        update_ttl: bool = True,
         **options,
     ) -> Any:
         """Execute the given user function with the provided arguments.
@@ -515,6 +534,10 @@ def exec(
                 - If it is provided, the policy will only use the filtered arguments to calculate the cache key and hash value.
                 - If it is not provided, the policy will use all arguments to calculate the cache key and hash value.
 
+            field_ttl: Time-to-live (in seconds) for the cached field.
+
+            update_ttl: Whether to update the TTL of cached items when they are accessed.
+
             options: Additional options passed from :meth:`decorate`'s `**kwargs`.
 
         Returns:
@@ -530,7 +553,7 @@ def exec(
         if not (isinstance(script_0, redis.commands.core.Script) and isinstance(script_1, redis.commands.core.Script)):
             raise TypeError("Can not eval redis lua script in asynchronous mode on a synchronous redis client")
         keys, hash_value, ext_args = self.prepare(user_function, user_args, user_kwds, bound)
-        cached_return_value = self.get(script_0, keys, hash_value, self.ttl, options, ext_args)
+        cached_return_value = self.get(script_0, keys, hash_value, update_ttl, self.ttl, options, ext_args)
         if cached_return_value is not None:
             return self.deserialize(cached_return_value, deserialize_func)
         user_retval = user_function(*user_args, **user_kwds)
@@ -541,6 +564,7 @@ def exec(
             hash_value,
             user_retval_serialized,
             self.maxsize,
+            update_ttl,
             self.ttl,
             0 if field_ttl is None else field_ttl,
             options,
@@ -557,9 +581,29 @@ async def aexec(
         deserialize_func: Optional[DeserializerT] = None,
         bound: Optional[BoundArguments] = None,
         field_ttl: int = 0,
+        update_ttl: bool = True,
         **options,
     ) -> Any:
-        """Asynchronous version of :meth:`.exec`"""
+        """Asynchronous version of :meth:`.exec`
+
+        Args:
+            user_function: The user function to execute.
+            user_args: Positional arguments to pass to the user function.
+            user_kwds: Keyword arguments to pass to the user function.
+            serialize_func: Custom serializer passed from :meth:`decorate`.
+            deserialize_func: Custom deserializer passed from :meth:`decorate`.
+
+            bound: Filtered bound arguments which will be used by the policy of the cache.
+
+                - If it is provided, the policy will only use the filtered arguments to calculate the cache key and hash value.
+                - If it is not provided, the policy will use all arguments to calculate the cache key and hash value.
+
+            field_ttl: Time-to-live (in seconds) for the cached field.
+
+            update_ttl: Whether to update the TTL of cached items when they are accessed.
+
+            options: Additional options passed from :meth:`decorate`'s `**kwargs`.
+        """
         if self._disabled.get():
             return await user_function(*user_args, **user_kwds)
         script_0, script_1 = self.policy.lua_scripts
@@ -569,7 +613,7 @@ async def aexec(
         ):
             raise TypeError("Can not eval redis lua script in synchronous mode on an asynchronous redis client")
         keys, hash_value, ext_args = self.prepare(user_function, user_args, user_kwds, bound)
-        cached = await self.aget(script_0, keys, hash_value, self.ttl, options, ext_args)
+        cached = await self.aget(script_0, keys, hash_value, update_ttl, self.ttl, options, ext_args)
         if cached is not None:
             return self.deserialize(cached, deserialize_func)
         user_retval = await user_function(*user_args, **user_kwds)
@@ -580,6 +624,7 @@ async def aexec(
             hash_value,
             user_retval_serialized,
             self.maxsize,
+            update_ttl,
             self.ttl,
             0 if field_ttl is None else field_ttl,
             options,
@@ -594,6 +639,7 @@ def decorate(
         *,
         serializer: Optional[SerializerSetterValueT] = None,
         ttl: Optional[int] = None,
+        update_ttl: Optional[bool] = None,
         excludes: Optional[Sequence[str]] = None,
         excludes_positional: Optional[Sequence[int]] = None,
         **options,
@@ -623,6 +669,12 @@ def decorate(
             Warning:
                 Only available in Redis Open Source version above 7.4
 
+            update_ttl: Whether to update the TTL of cached items when they are accessed.
+
+                If not provided, the default is the value set in the cache instance.
+                When ``True``, accessing a cached item will reset its TTL.
+                When ``False``, accessing a cached item will not update its TTL.
+
             excludes: Optional sequence of parameter names specifying keyword arguments to exclude from cache key generation.
 
                 Example: `excludes=["token"]`
@@ -690,6 +742,7 @@ def my_func(a, b):
         elif serializer is not None:
             serialize_func, deserialize_func = serializer
         field_ttl = 0 if ttl is None else int(ttl)
+        effective_update_ttl = self.update_ttl if update_ttl is None else update_ttl
 
         def decorator(user_func: CallableTV) -> CallableTV:
             @wraps(user_func)
@@ -703,6 +756,7 @@ def wrapper(*user_args, **user_kwargs):
                     deserialize_func,
                     bound,
                     field_ttl,
+                    effective_update_ttl,
                     **options,
                 )
 
@@ -717,6 +771,7 @@ async def awrapper(*user_args, **user_kwargs):
                     deserialize_func,
                     bound,
                     field_ttl,
+                    effective_update_ttl,
                     **options,
                 )
 

src/redis_func_cache/lua/fifo_get.lua

@@ -1,20 +1,21 @@
-
 --[[
   FIFO (First-In-First-Out) cache get operation using zset order.
   KEYS[1]: Redis sorted set key for cache hashes (score = order)
   KEYS[2]: Redis hash key for cache values
-  ARGV[1]: TTL for both keys (number, seconds)
-  ARGV[2]: hash key to retrieve
+  ARGV[1]: update ttl flag (1 for update ttl, 0 for fixed ttl)
+  ARGV[2]: TTL for both keys (number, seconds)
+  ARGV[3]: hash key to retrieve
   Returns: value if found, otherwise nil. Cleans up stale entries.
 ]]
 local zset_key = KEYS[1]
 local hmap_key = KEYS[2]
 
-local ttl = ARGV[1]
-local hash = ARGV[2]
+local update_ttl_flag = ARGV[1]
+local ttl = ARGV[2]
+local hash = ARGV[3]
 
--- Set TTL if specified
-if tonumber(ttl) > 0 then
+-- Set TTL if specified and update_ttl_flag is set
+if tonumber(ttl) > 0 and update_ttl_flag == "1" then
     redis.call('EXPIRE', zset_key, ttl)
     redis.call('EXPIRE', hmap_key, ttl)
 end
@@ -30,3 +31,5 @@ elseif rnk then
 elseif val then
     redis.call('HDEL', hmap_key, hash) -- remove stale hash value
 end
+
+return nil