limits 4.0.0__py3-none-any.whl → 4.1__py3-none-any.whl

limits/aio/storage/redis.py

@@ -5,9 +5,13 @@ from typing import TYPE_CHECKING, cast
 from deprecated.sphinx import versionadded
 from packaging.version import Version
 
-from limits.aio.storage.base import MovingWindowSupport, Storage
+from limits.aio.storage.base import (
+    MovingWindowSupport,
+    SlidingWindowCounterSupport,
+    Storage,
+)
 from limits.errors import ConfigurationError
-from limits.typing import AsyncRedisClient, Dict, Optional, Tuple, Type, Union
+from limits.typing import AsyncRedisClient, Optional, Type, Union
 from limits.util import get_package_data
 
 if TYPE_CHECKING:
@@ -24,9 +28,15 @@ class RedisInteractor:
     )
     SCRIPT_CLEAR_KEYS = get_package_data(f"{RES_DIR}/clear_keys.lua")
     SCRIPT_INCR_EXPIRE = get_package_data(f"{RES_DIR}/incr_expire.lua")
+    SCRIPT_SLIDING_WINDOW = get_package_data(f"{RES_DIR}/sliding_window.lua")
+    SCRIPT_ACQUIRE_SLIDING_WINDOW = get_package_data(
+        f"{RES_DIR}/acquire_sliding_window.lua"
+    )
 
     lua_moving_window: "coredis.commands.Script[bytes]"
-    lua_acquire_window: "coredis.commands.Script[bytes]"
+    lua_acquire_moving_window: "coredis.commands.Script[bytes]"
+    lua_sliding_window: "coredis.commands.Script[bytes]"
+    lua_acquire_sliding_window: "coredis.commands.Script[bytes]"
     lua_clear_keys: "coredis.commands.Script[bytes]"
     lua_incr_expire: "coredis.commands.Script[bytes]"
 
@@ -78,14 +88,14 @@ class RedisInteractor:
 
     async def get_moving_window(
         self, key: str, limit: int, expiry: int
-    ) -> Tuple[float, int]:
+    ) -> tuple[float, int]:
         """
         returns the starting point and the number of entries in the moving
         window
 
         :param key: rate limit key
         :param expiry: expiry of entry
-        :return: (start of window, number of acquired entries)
+        :return: (previous count, previous TTL, current count, current TTL)
         """
         key = self.prefixed_key(key)
         timestamp = time.time()
@@ -96,6 +106,23 @@ class RedisInteractor:
             return float(window[0]), window[1]  # type: ignore
         return timestamp, 0
 
+    async def get_sliding_window(
+        self, key: str, expiry: int
+    ) -> tuple[int, float, int, float]:
+        previous_key = self.prefixed_key(self._previous_window_key(key))
+        current_key = self.prefixed_key(self._current_window_key(key))
+
+        if window := await self.lua_sliding_window.execute(
+            [previous_key, current_key], [expiry]
+        ):
+            return (
+                int(window[0] or 0),  # type: ignore
+                max(0, float(window[1] or 0)) / 1000,  # type: ignore
+                int(window[2] or 0),  # type: ignore
+                max(0, float(window[3] or 0)) / 1000,  # type: ignore
+            )
+        return 0, 0.0, 0, 0.0
+
     async def _acquire_entry(
         self,
         key: str,
@@ -112,12 +139,27 @@ class RedisInteractor:
         """
         key = self.prefixed_key(key)
         timestamp = time.time()
-        acquired = await self.lua_acquire_window.execute(
+        acquired = await self.lua_acquire_moving_window.execute(
             [key], [timestamp, limit, expiry, amount]
         )
 
         return bool(acquired)
 
+    async def _acquire_sliding_window_entry(
+        self,
+        previous_key: str,
+        current_key: str,
+        limit: int,
+        expiry: int,
+        amount: int = 1,
+    ) -> bool:
+        previous_key = self.prefixed_key(previous_key)
+        current_key = self.prefixed_key(current_key)
+        acquired = await self.lua_acquire_sliding_window.execute(
+            [previous_key, current_key], [limit, expiry, amount]
+        )
+        return bool(acquired)
+
     async def _get_expiry(self, key: str, connection: AsyncRedisClient) -> float:
         """
         :param key: the key to get the expiry for
@@ -140,9 +182,35 @@ class RedisInteractor:
         except:  # noqa
             return False
 
+    def _current_window_key(self, key: str) -> str:
+        """
+        Return the current window's storage key (Sliding window strategy)
+
+        Contrary to other strategies that have one key per rate limit item,
+        this strategy has two keys per rate limit item than must be on the same machine.
+        To keep the current key and the previous key on the same Redis cluster node,
+        curly braces are added.
+
+        Eg: "{constructed_key}"
+        """
+        return f"{{{key}}}"
+
+    def _previous_window_key(self, key: str) -> str:
+        """
+        Return the previous window's storage key (Sliding window strategy).
+
+        Curvy braces are added on the common pattern with the current window's key,
+        so the current and the previous key are stored on the same Redis cluster node.
+
+        Eg: "{constructed_key}/-1"
+        """
+        return f"{self._current_window_key(key)}/-1"
+
 
 @versionadded(version="2.1")
-class RedisStorage(RedisInteractor, Storage, MovingWindowSupport):
+class RedisStorage(
+    RedisInteractor, Storage, MovingWindowSupport, SlidingWindowCounterSupport
+):
     """
     Rate limit storage with redis as backend.
 
@@ -200,18 +268,22 @@ class RedisStorage(RedisInteractor, Storage, MovingWindowSupport):
     @property
     def base_exceptions(
         self,
-    ) -> Union[Type[Exception], Tuple[Type[Exception], ...]]:  # pragma: no cover
+    ) -> Union[Type[Exception], tuple[Type[Exception], ...]]:  # pragma: no cover
         return self.dependency.exceptions.RedisError  # type: ignore[no-any-return]
 
     def initialize_storage(self, _uri: str) -> None:
         # all these methods are coroutines, so must be called with await
         self.lua_moving_window = self.storage.register_script(self.SCRIPT_MOVING_WINDOW)
-        self.lua_acquire_window = self.storage.register_script(
+        self.lua_acquire_moving_window = self.storage.register_script(
             self.SCRIPT_ACQUIRE_MOVING_WINDOW
         )
         self.lua_clear_keys = self.storage.register_script(self.SCRIPT_CLEAR_KEYS)
-        self.lua_incr_expire = self.storage.register_script(
-            RedisStorage.SCRIPT_INCR_EXPIRE
+        self.lua_incr_expire = self.storage.register_script(self.SCRIPT_INCR_EXPIRE)
+        self.lua_sliding_window = self.storage.register_script(
+            self.SCRIPT_SLIDING_WINDOW
+        )
+        self.lua_acquire_sliding_window = self.storage.register_script(
+            self.SCRIPT_ACQUIRE_SLIDING_WINDOW
         )
 
     async def incr(
@@ -261,6 +333,19 @@ class RedisStorage(RedisInteractor, Storage, MovingWindowSupport):
 
         return await super()._acquire_entry(key, limit, expiry, self.storage, amount)
 
+    async def acquire_sliding_window_entry(
+        self,
+        key: str,
+        limit: int,
+        expiry: int,
+        amount: int = 1,
+    ) -> bool:
+        current_key = self._current_window_key(key)
+        previous_key = self._previous_window_key(key)
+        return await super()._acquire_sliding_window_entry(
+            previous_key, current_key, limit, expiry, amount
+        )
+
     async def get_expiry(self, key: str) -> float:
         """
         :param key: the key to get the expiry for
@@ -302,7 +387,7 @@ class RedisClusterStorage(RedisStorage):
     The storage schemes for redis cluster to be used in an async context
     """
 
-    DEFAULT_OPTIONS: Dict[str, Union[float, str, bool]] = {
+    DEFAULT_OPTIONS: dict[str, Union[float, str, bool]] = {
         "max_connections": 1000,
     }
     "Default options passed to :class:`coredis.RedisCluster`"
@@ -322,7 +407,7 @@ class RedisClusterStorage(RedisStorage):
          available or if the redis host cannot be pinged.
         """
         parsed = urllib.parse.urlparse(uri)
-        parsed_auth: Dict[str, Union[float, str, bool]] = {}
+        parsed_auth: dict[str, Union[float, str, bool]] = {}
 
         if parsed.username:
             parsed_auth["username"] = parsed.username
@@ -386,7 +471,7 @@ class RedisSentinelStorage(RedisStorage):
         uri: str,
         service_name: Optional[str] = None,
         use_replicas: bool = True,
-        sentinel_kwargs: Optional[Dict[str, Union[float, str, bool]]] = None,
+        sentinel_kwargs: Optional[dict[str, Union[float, str, bool]]] = None,
         **options: Union[float, str, bool],
     ):
         """
@@ -407,7 +492,7 @@ class RedisSentinelStorage(RedisStorage):
         sentinel_configuration = []
         connection_options = options.copy()
         sentinel_options = sentinel_kwargs.copy() if sentinel_kwargs else {}
-        parsed_auth: Dict[str, Union[float, str, bool]] = {}
+        parsed_auth: dict[str, Union[float, str, bool]] = {}
 
         if parsed.username:
             parsed_auth["username"] = parsed.username

limits/aio/strategies.py

@@ -2,13 +2,18 @@
 Asynchronous rate limiting strategies
 """
 
+import time
 from abc import ABC, abstractmethod
-from typing import cast
+from math import floor, inf
+
+from deprecated.sphinx import deprecated, versionadded
 
 from ..limits import RateLimitItem
 from ..storage import StorageTypes
+from ..typing import cast
 from ..util import WindowStats
 from .storage import MovingWindowSupport, Storage
+from .storage.base import SlidingWindowCounterSupport
 
 
 class RateLimiter(ABC):
@@ -183,6 +188,121 @@ class FixedWindowRateLimiter(RateLimiter):
         return WindowStats(reset, remaining)
 
 
+@versionadded(version="4.1")
+class SlidingWindowCounterRateLimiter(RateLimiter):
+    """
+    Reference: :ref:`strategies:sliding window counter`
+    """
+
+    def __init__(self, storage: StorageTypes):
+        if not hasattr(storage, "get_sliding_window") or not hasattr(
+            storage, "acquire_sliding_window_entry"
+        ):
+            raise NotImplementedError(
+                "SlidingWindowCounterRateLimiting is not implemented for storage "
+                "of type %s" % storage.__class__
+            )
+        super().__init__(storage)
+
+    def _weighted_count(
+        self,
+        item: RateLimitItem,
+        previous_count: int,
+        previous_expires_in: float,
+        current_count: int,
+    ) -> float:
+        """
+        Return the approximated by weighting the previous window count and adding the current window count.
+        """
+        return previous_count * previous_expires_in / item.get_expiry() + current_count
+
+    async def hit(self, item: RateLimitItem, *identifiers: str, cost: int = 1) -> bool:
+        """
+        Consume the rate limit
+
+        :param item: The rate limit item
+        :param identifiers: variable list of strings to uniquely identify this
+         instance of the limit
+        :param cost: The cost of this hit, default 1
+        """
+        return await cast(
+            SlidingWindowCounterSupport, self.storage
+        ).acquire_sliding_window_entry(
+            item.key_for(*identifiers),
+            item.amount,
+            item.get_expiry(),
+            cost,
+        )
+
+    async def test(self, item: RateLimitItem, *identifiers: str, cost: int = 1) -> bool:
+        """
+        Check if the rate limit can be consumed
+
+        :param item: The rate limit item
+        :param identifiers: variable list of strings to uniquely identify this
+         instance of the limit
+        :param cost: The expected cost to be consumed, default 1
+        """
+
+        previous_count, previous_expires_in, current_count, _ = await cast(
+            SlidingWindowCounterSupport, self.storage
+        ).get_sliding_window(item.key_for(*identifiers), item.get_expiry())
+
+        return (
+            self._weighted_count(
+                item, previous_count, previous_expires_in, current_count
+            )
+            < item.amount - cost + 1
+        )
+
+    async def get_window_stats(
+        self, item: RateLimitItem, *identifiers: str
+    ) -> WindowStats:
+        """
+        Query the reset time and remaining amount for the limit.
+
+        :param item: The rate limit item
+        :param identifiers: variable list of strings to uniquely identify this
+         instance of the limit
+        :return: (reset time, remaining)
+        """
+
+        (
+            previous_count,
+            previous_expires_in,
+            current_count,
+            current_expires_in,
+        ) = await cast(SlidingWindowCounterSupport, self.storage).get_sliding_window(
+            item.key_for(*identifiers), item.get_expiry()
+        )
+
+        remaining = max(
+            0,
+            item.amount
+            - floor(
+                self._weighted_count(
+                    item, previous_count, previous_expires_in, current_count
+                )
+            ),
+        )
+
+        now = time.time()
+
+        if not (previous_count or current_count):
+            return WindowStats(now, remaining)
+
+        expiry = item.get_expiry()
+
+        previous_reset_in, current_reset_in = inf, inf
+        if previous_count:
+            previous_reset_in = previous_expires_in % (expiry / previous_count)
+        if current_count:
+            current_reset_in = current_expires_in % expiry
+
+        return WindowStats(now + min(previous_reset_in, current_reset_in), remaining)
+
+
+@deprecated(version="4.1")
 class FixedWindowElasticExpiryRateLimiter(FixedWindowRateLimiter):
     """
     Reference: :ref:`strategies:fixed window with elastic expiry`
@@ -208,6 +328,7 @@ class FixedWindowElasticExpiryRateLimiter(FixedWindowRateLimiter):
 
 
 STRATEGIES = {
+    "sliding-window-counter": SlidingWindowCounterRateLimiter,
     "fixed-window": FixedWindowRateLimiter,
     "fixed-window-elastic-expiry": FixedWindowElasticExpiryRateLimiter,
     "moving-window": MovingWindowRateLimiter,

limits/limits.py

@@ -3,14 +3,13 @@
 from __future__ import annotations
 
 from functools import total_ordering
-from typing import Dict, NamedTuple, Optional, Tuple, Type, Union, cast
 
-from limits.typing import ClassVar, List
+from limits.typing import ClassVar, NamedTuple, cast
 
 
-def safe_string(value: Union[bytes, str, int]) -> str:
+def safe_string(value: bytes | str | int | float) -> str:
     """
-    converts a byte/str or int to a str
+    normalize a byte/str/int or float to a str
     """
 
     if isinstance(value, bytes):
@@ -33,15 +32,15 @@ TIME_TYPES = dict(
     second=Granularity(1, "second"),
 )
 
-GRANULARITIES: Dict[str, Type[RateLimitItem]] = {}
+GRANULARITIES: dict[str, type[RateLimitItem]] = {}
 
 
 class RateLimitItemMeta(type):
     def __new__(
         cls,
         name: str,
-        parents: Tuple[type, ...],
-        dct: Dict[str, Union[Granularity, List[str]]],
+        parents: tuple[type, ...],
+        dct: dict[str, Granularity | list[str]],
     ) -> RateLimitItemMeta:
         if "__slots__" not in dct:
             dct["__slots__"] = []
@@ -49,7 +48,7 @@ class RateLimitItemMeta(type):
 
         if "GRANULARITY" in dct:
             GRANULARITIES[dct["GRANULARITY"][1]] = cast(
-                Type[RateLimitItem], granularity
+                type[RateLimitItem], granularity
             )
 
         return granularity
@@ -77,7 +76,7 @@ class RateLimitItem(metaclass=RateLimitItemMeta):
     """
 
     def __init__(
-        self, amount: int, multiples: Optional[int] = 1, namespace: str = "LIMITER"
+        self, amount: int, multiples: int | None = 1, namespace: str = "LIMITER"
     ):
         self.namespace = namespace
         self.amount = int(amount)
@@ -101,14 +100,14 @@ class RateLimitItem(metaclass=RateLimitItemMeta):
 
         return self.GRANULARITY.seconds * self.multiples
 
-    def key_for(self, *identifiers: str) -> str:
+    def key_for(self, *identifiers: bytes | str | int | float) -> str:
         """
         Constructs a key for the current limit and any additional
         identifiers provided.
 
         :param identifiers: a list of strings to append to the key
         :return: a string key identifying this resource with
-         each identifier appended with a '/' delimiter.
+         each identifier separated with a '/' delimiter.
         """
         remainder = "/".join(
             [safe_string(k) for k in identifiers]

limits/resources/redis/lua_scripts/acquire_sliding_window.lua

@@ -0,0 +1,45 @@
+-- Time is in milliseconds in this script: TTL, expiry...
+
+local limit = tonumber(ARGV[1])
+local expiry = tonumber(ARGV[2]) * 1000
+local amount = tonumber(ARGV[3])
+
+if amount > limit then
+    return false
+end
+
+local current_ttl = tonumber(redis.call('pttl', KEYS[2]))
+
+if current_ttl > 0 and current_ttl < expiry then
+    -- Current window expired, shift it to the previous window
+    redis.call('rename', KEYS[2], KEYS[1])
+    redis.call('set', KEYS[2], 0, 'PX', current_ttl + expiry)
+end
+
+local previous_count = tonumber(redis.call('get', KEYS[1])) or 0
+local previous_ttl = tonumber(redis.call('pttl', KEYS[1])) or 0
+local current_count = tonumber(redis.call('get', KEYS[2])) or 0
+current_ttl = tonumber(redis.call('pttl', KEYS[2])) or 0
+
+-- If the values don't exist yet, consider the TTL is 0
+if previous_ttl <= 0 then
+    previous_ttl = 0
+end
+if current_ttl <= 0 then
+    current_ttl = 0
+end
+local weighted_count = math.floor(previous_count * previous_ttl / expiry) + current_count
+
+if (weighted_count + amount) > limit then
+    return false
+end
+
+-- If the current counter exists, increase its value
+if redis.call('exists', KEYS[2]) == 1 then
+    redis.call('incrby', KEYS[2], amount)
+else
+    -- Otherwise, set the value with twice the expiry time
+    redis.call('set', KEYS[2], amount, 'PX', expiry * 2)
+end
+
+return true

limits/resources/redis/lua_scripts/sliding_window.lua

@@ -0,0 +1,17 @@
+local expiry = tonumber(ARGV[1]) * 1000
+local previous_count = redis.call('get', KEYS[1])
+local previous_ttl = redis.call('pttl', KEYS[1])
+local current_count = redis.call('get', KEYS[2])
+local current_ttl = redis.call('pttl', KEYS[2])
+
+if current_ttl > 0 and current_ttl < expiry then
+    -- Current window expired, shift it to the previous window
+    redis.call('rename', KEYS[2], KEYS[1])
+    redis.call('set', KEYS[2], 0, 'PX', current_ttl + expiry)
+    previous_count = redis.call('get', KEYS[1])
+    previous_ttl = redis.call('pttl', KEYS[1])
+    current_count = redis.call('get', KEYS[2])
+    current_ttl = redis.call('pttl', KEYS[2])
+end
+
+return {previous_count, previous_ttl, current_count, current_ttl}

limits/storage/__init__.py

@@ -4,12 +4,12 @@ Implementations of storage backends to be used with
 """
 
 import urllib
-from typing import Union, cast
 
-import limits
+import limits  # noqa
 
 from ..errors import ConfigurationError
-from .base import MovingWindowSupport, Storage
+from ..typing import Union, cast
+from .base import MovingWindowSupport, SlidingWindowCounterSupport, Storage
 from .etcd import EtcdStorage
 from .memcached import MemcachedStorage
 from .memory import MemoryStorage
@@ -32,9 +32,9 @@ def storage_from_string(
 
         from limits.storage import storage_from_string
 
-        memory = from_string("memory://")
-        memcached = from_string("memcached://localhost:11211")
-        redis = from_string("redis://localhost:6379")
+        memory = storage_from_string("memory://")
+        memcached = storage_from_string("memcached://localhost:11211")
+        redis = storage_from_string("redis://localhost:6379")
 
     The same function can be used to construct the :ref:`storage:async storage`
     variants, for example::
@@ -67,6 +67,7 @@ __all__ = [
     "storage_from_string",
     "Storage",
     "MovingWindowSupport",
+    "SlidingWindowCounterSupport",
     "EtcdStorage",
     "MongoDBStorageBase",
     "MemoryStorage",