Merge pull request #58 from python-ellar/ellar_081_upgrade

Ellar 081 upgrade

Author: eadwinCode

README.md

@@ -44,7 +44,7 @@ class AppModule:
 
 ```python
 from ellar.common import Controller, get
-from ellar_throttler import Throttle
+from ellar_throttler import Throttle, AnonymousThrottler, UserThrottler
 from ellar.di import injectable
 
 
@@ -63,7 +63,7 @@ class AppService:
         return {message: True}
 
 
-@Throttle(apply_interceptor=True)
+@Throttle(intercept=True)
 @Controller("/limit")
 class LimitController:
     def __init__(self, app_service: AppService):
@@ -77,6 +77,11 @@ class LimitController:
     @Throttle(anon={"limit": 3, "ttl": 5}, user={"limit": 3, "ttl": 3}) # overriding anon and user throttler config
     def get_shorter(self, use_auth: bool):
         return self.app_service.success(use_auth)
+
+    @get("/shorter-inline-throttling")
+    @Throttle(AnonymousThrottler(ttl=5, limit=3), UserThrottler(ttl=3, limit=3)) # overriding global throttling options
+    def get_shorter_inline_version(self, use_auth: bool):
+        return self.app_service.success(use_auth)
 ```
 
 ## References

ellar_throttler/__init__.py

@@ -1,6 +1,6 @@
 """A rate limiting module for Ellar"""
 
-__version__ = "0.1.5"
+__version__ = "0.1.7"
 
 from .decorators import SkipThrottle, Throttle
 from .exception import ThrottledException

ellar_throttler/constants.py

@@ -2,3 +2,4 @@
 THROTTLER_TTL = "THROTTLER:TTL"
 THROTTLER_OPTIONS = "THROTTLER:MODULE_OPTIONS"
 THROTTLER_SKIP = "THROTTLER:SKIP"
+INLINE_THROTTLERS = "INLINE_THROTTLERS:MODELS"

ellar_throttler/decorators.py

@@ -3,7 +3,9 @@
 from ellar.common import constants, set_metadata
 from ellar.reflect import reflect
 
-from .constants import THROTTLER_LIMIT, THROTTLER_SKIP, THROTTLER_TTL
+from ellar_throttler.model.base import BaseThrottler
+
+from .constants import INLINE_THROTTLERS, THROTTLER_LIMIT, THROTTLER_SKIP, THROTTLER_TTL
 from .throttler_interceptor import ThrottlerInterceptor
 
 
@@ -14,7 +16,9 @@ class _Config(t.TypedDict):
     ttl: int
 
 
-def Throttle(*, apply_interceptor: bool = False, **kwargs: _Config) -> t.Callable:
+def Throttle(
+    *throttlers: BaseThrottler, intercept: bool = False, **kwargs: _Config
+) -> t.Callable:
     """
     Adds metadata to the target which will be handled by the ThrottlerGuard to
     handle incoming requests based on the given metadata.
@@ -24,11 +28,14 @@ def Throttle(*, apply_interceptor: bool = False, **kwargs: _Config) -> t.Callabl
 
     @Throttle(throttler_model_name={'limit':20, 'ttl':300})
     class ControllerSample:
-        @Throttle('user', limit=20, ttl=300)
+        @Throttle(user={'limit':20, 'ttl':300})
         async def index(self):
             ...
 
-    :param apply_interceptor: Indicates whether to apply ThrottlerInterceptor
+    @Throttle(AnonymousThrottler(ttl=5, limit=3), UserThrottler(ttl=3, limit=3)) # overriding global throttling options
+    class ControllerSample:
+        pass
+    :param intercept: Indicates whether to apply ThrottlerInterceptor
     :param kwargs: Throttler name used in setting up ThrottlerModule with overriding config
     :return: Callable
     """
@@ -39,7 +46,10 @@ def decorator(func_: t.Callable) -> t.Callable:
                 reflect.define_metadata(f"{THROTTLER_TTL}-{k}", v.get("ttl"), func_)
                 reflect.define_metadata(f"{THROTTLER_LIMIT}-{k}", v.get("limit"), func_)
 
-        if apply_interceptor:
+        if throttlers:
+            reflect.define_metadata(INLINE_THROTTLERS, list(throttlers), func_)
+
+        if intercept:
             return set_metadata(constants.ROUTE_INTERCEPTORS, [ThrottlerInterceptor])(  # type:ignore[no-any-return]
                 func_
             )

ellar_throttler/model/base.py

@@ -7,8 +7,8 @@
 from ellar.utils import get_name
 from starlette.responses import Response
 
-from ellar_throttler import IThrottlerStorage, ThrottledException
-from ellar_throttler.interfaces import IThrottleModel
+from ellar_throttler.exception import ThrottledException
+from ellar_throttler.interfaces import IThrottleModel, IThrottlerStorage
 
 
 class BaseThrottler(IThrottleModel, ABC):

ellar_throttler/module.py

@@ -1,14 +1,19 @@
 import functools
 import typing as t
 
+from ellar.cache import CacheModule
 from ellar.common import IExecutionContext, IModuleSetup, Module
+from ellar.common.exceptions import ImproperConfiguration
 from ellar.core import Config, ModuleSetup
-from ellar.core.modules import DynamicModule, ModuleBase
+from ellar.core.modules import DynamicModule, ModuleBase, ModuleRefBase
 from ellar.di import ProviderConfig
 
 from ellar_throttler.interfaces import IThrottleModel, IThrottlerStorage
 from ellar_throttler.throttler_module_options import ThrottlerModuleOptions
-from ellar_throttler.throttler_service import ThrottlerStorageService
+from ellar_throttler.throttler_service import (
+    CacheThrottlerStorageService,
+    ThrottlerStorageService,
+)
 
 
 class _Config(t.TypedDict):
@@ -19,8 +24,23 @@ class _Config(t.TypedDict):
     skip_if: t.Optional[t.Callable[[IExecutionContext], bool]]
 
 
-@Module()
+@Module(name="ThrottlerModule", exports=[IThrottlerStorage, ThrottlerModuleOptions])
 class ThrottlerModule(ModuleBase, IModuleSetup):
+    @classmethod
+    def post_build(cls, module_ref: "ModuleRefBase") -> None:
+        storage = module_ref.providers.get(IThrottlerStorage)
+        if storage.use_class and (  # type:ignore[union-attr]
+            storage.use_class == CacheThrottlerStorageService  # type:ignore[union-attr]
+            or issubclass(storage.use_class, CacheThrottlerStorageService)  # type:ignore[union-attr]
+        ):
+            try:
+                module_ref.tree_manager.add_module_dependency(cls, CacheModule)
+            except ValueError:
+                raise ImproperConfiguration(
+                    f"Using {CacheThrottlerStorageService} as storage type requires {CacheModule} setup. "
+                    f"See https://python-ellar.github.io/ellar/security/rate-limit/"
+                ) from None
+
     @classmethod
     def setup(
         cls,
@@ -66,7 +86,7 @@ def register_setup(cls, **override_config: t.Any) -> ModuleSetup:
 
     @staticmethod
     def __register_setup_factory(
-        module: t.Type["ThrottlerModule"],
+        module_ref: ModuleRefBase,
         config: Config,
         override_config: t.Dict[str, t.Any],
     ) -> DynamicModule:
@@ -81,7 +101,7 @@ def __register_setup_factory(
             schema = ThrottlerModuleOptions.model_validate(
                 defined_config, from_attributes=True
             )
-
+            module = t.cast(t.Type[ThrottlerModule], module_ref.module)
             return module.__setup_module(schema, storage)
         raise RuntimeError(
             "Could not find `ELLAR_THROTTLER_CONFIG` in application config."

ellar_throttler/throttler_interceptor.py

@@ -4,7 +4,7 @@
 from ellar.core.services import Reflector
 from ellar.di import injectable
 
-from .constants import THROTTLER_LIMIT, THROTTLER_SKIP, THROTTLER_TTL
+from .constants import INLINE_THROTTLERS, THROTTLER_LIMIT, THROTTLER_SKIP, THROTTLER_TTL
 from .interfaces import IThrottlerStorage
 from .throttler_module_options import ThrottlerModuleOptions
 
@@ -37,7 +37,13 @@ async def intercept(
         if self.reflector.get_all_and_override(THROTTLER_SKIP, handler, class_ref):
             return await next_interceptor()
 
-        for throttler in self.options.throttlers:
+        inline_throttlers = (
+            self.reflector.get_all_and_override(INLINE_THROTTLERS, handler, class_ref)
+            or []
+        )
+        throttlers = inline_throttlers or self.options.throttlers
+
+        for throttler in throttlers:
             # Continue if throttler was skipped
             skip_route_throttle = self.reflector.get_all_and_override(
                 f"{THROTTLER_SKIP}-{throttler.name}", handler, class_ref

ellar_throttler/throttler_service.py

@@ -76,9 +76,10 @@ async def increment(self, key: str, ttl: int) -> ThrottlerStorageRecord:
 
 @injectable()
 class CacheThrottlerStorageService(IThrottlerStorage):
+    cache_backend: str = "default"
+
     def __init__(self, cache_service: ICacheService) -> None:
         self._cache_service = cache_service
-        self.cache_backend = "default"
 
     @property
     def storage(self) -> t.Any:  # pragma: no cover

pyproject.toml

@@ -40,7 +40,7 @@ classifiers = [
 ]
 
 dependencies = [
-    "ellar >= 0.7.0"
+    "ellar >= 0.8.2"
 ]
 
 

samples/ellar-with-throttling/README.md

@@ -0,0 +1,13 @@
+## Introduction
+A simple project to demonstrate route throttling technique in ellar application using ellar-throttling package.
+
+## Project setup
+```
+pip install -r requirements.txt
+```
+
+## Development Server
+```
+python manage.py runserver --reload
+```
+Visit Swagger Docs: [http://localhost:8000/docs](http://localhost:8000/docs)