Merge pull request #20 from eadwinCode/throttling

Throttling

Author: eadwinCode

README.md

@@ -116,5 +116,3 @@ You will see the automatic interactive API documentation (provided by <a href="h
 ![Swagger UI](docs/docs/images/ui_swagger_preview_readme.gif)
 ## What next?
 - To support this project, please give star it on Github
-- API Throttling
-

docs/Makefile

@@ -0,0 +1,179 @@
+# **Throttling**
+
+Throttling can be seen as a permission that determines if a request should be authorized. 
+It indicates a temporary state used to control the rate of requests that clients can make to an API.
+
+```python
+from ninja_extra import NinjaExtraAPI, throttle
+api = NinjaExtraAPI()
+
+@api.get('/users')
+@throttle  # this will apply default throttle classes [UserRateThrottle, AnonRateThrottle]
+def my_throttled_endpoint(request):
+    return 'foo'
+```
+
+!!! info
+    The above example won't be throttled because the default scope for `UserRateThrottle` and `AnonRateThrottle`
+    is `none`
+
+## **Multiple Throttling**
+Django-ninja-extra throttle supposes multiple throttles which is useful to impose different
+constraints, which could be burst throttling rate or sustained throttling rates, on an API.
+for example, you might want to limit a user to a maximum of 60 requests per minute, and 1000 requests per day.
+
+```python
+from ninja_extra import NinjaExtraAPI, throttle
+from ninja_extra.throttling import UserRateThrottle
+api = NinjaExtraAPI()
+
+class User60MinRateThrottle(UserRateThrottle):
+    rate = "60/min"
+    scope = "minutes"
+
+
+class User1000PerDayRateThrottle(UserRateThrottle):
+    rate = "1000/day"
+    scope = "days"
+
+@api.get('/users')
+@throttle(User60MinRateThrottle, User1000PerDayRateThrottle)
+def my_throttled_endpoint(request):
+    return 'foo'
+
+```
+## **Throttling Policy Settings**
+You can set globally default throttling classes and rates in your project `settings.py` by overriding the keys below:
+```python
+# django settings.py
+NINJA_EXTRA = {
+    'THROTTLE_CLASSES': [
+        "ninja_extra.throttling.AnonRateThrottle",
+        "ninja_extra.throttling.UserRateThrottle",
+    ],
+    'THROTTLE_RATES': {
+        'user': '1000/day',
+        'anon': '100/day',
+    },
+    'NUM_PROXIES': None
+}
+```
+The rate descriptions used in `THROTTLE_RATES` may include `second`, `minute`, `hour` or `day` as the throttle period.
+
+```python
+from ninja_extra import NinjaExtraAPI, throttle
+from ninja_extra.throttling import UserRateThrottle
+
+api = NinjaExtraAPI()
+
+@api.get('/users')
+@throttle(UserRateThrottle)
+def my_throttled_endpoint(request):
+    return 'foo'
+```
+
+## **Clients Identification**
+Clients are identified by x-Forwarded-For in HTTP header and REMOTE_ADDR from WSGI variable.
+These are unique identities which identifies clients IP addresses used for throttling.
+`X-Forwarded-For` is preferable over `REMOTE_ADDR` and is used as so.
+
+#### **Limit Clients Proxies**
+If you need to strictly identify unique client IP addresses, you'll need to first configure the number of application proxies that the API runs behind by setting the `NUM_PROXIES` setting. This setting should be an integer of zero or more.
+If set to non-zero then the client IP will be identified as being the last IP address in the X-Forwarded-For header, once any application proxy IP addresses have first been excluded. If set to zero, then the REMOTE_ADDR value will always be used as the identifying IP address.
+It is important to understand that if you configure the `NUM_PROXIES` setting, then all clients behind a unique [NAT'd](https://en.wikipedia.org/wiki/Network_address_translation) gateway will be treated as a single client.
+
+!!! info
+    Further context on how the X-Forwarded-For header works, and identifying a remote client IP can be found here.
+
+## **Throttling Model Cache setup**
+The throttling models used in django-ninja-extra utilizes Django cache backend. It uses the `default` value of [`LocMemCache`]()
+See Django's [cache documentation](https://docs.djangoproject.com/en/stable/topics/cache/#setting-up-the-cache) for more details.
+
+If you dont want to use the default cache defined in throttle model, here is an example on how to define a different cache for a throttling model
+```python
+
+from django.core.cache import caches
+from ninja_extra.throttling import AnonRateThrottle
+
+
+class CustomAnonRateThrottle(AnonRateThrottle):
+    cache = caches['alternate']
+```
+# **API Reference**
+
+## **AnonRateThrottle**
+`AnonRateThrottle` model is for throttling unauthenticated users using their IP address as key to throttle against.
+It is suitable for restricting rate of requests from an unknown source
+
+Request Permission is determined by:
+- `rate` defined in derived class
+- `anon` scope defined in `THROTTLE_RATES` in `NINJA_EXTRA` settings in `settings.py` 
+
+## **UserRateThrottle**
+`UserRateThrottle` model is for throttling authenticated users using user id or pk to generate a key to throttle against.
+Unauthenticated requests will fall back to using the IP address of the incoming request to generate a unique key to throttle against.
+
+Request Permission is determined by:
+- `rate` defined in derived class
+- `user` scope defined in `THROTTLE_RATES` in `NINJA_EXTRA` settings in `settings.py` 
+
+You can use multiple user throttle rates for a `UserRateThrottle` model, for example:
+```python
+# example/throttles.py
+from ninja_extra.throttling import UserRateThrottle
+
+
+class BurstRateThrottle(UserRateThrottle):
+    scope = 'burst'
+
+
+class SustainedRateThrottle(UserRateThrottle):
+    scope = 'sustained'
+```
+
+```python
+# django settings.py
+NINJA_EXTRA = {
+    'THROTTLE_CLASSES': [
+        'example.throttles.BurstRateThrottle',
+        'example.throttles.SustainedRateThrottle'
+    ],
+    'THROTTLE_RATES': {
+        'burst': '60/min',
+        'sustained': '1000/day'
+    }
+}
+```
+## **DynamicRateThrottle**
+`DynamicRateThrottle` model is for throttling authenticated and unauthenticated users in similar way as `UserRateThrottle`. 
+Its key feature is in the ability to dynamically set `scope` where its used.
+for an example:
+we can defined a scope in settings
+
+```python
+# django settings.py
+NINJA_EXTRA = {
+    'THROTTLE_RATES': {
+        'burst': '60/min',
+        'sustained': '1000/day'
+    }
+}
+```
+
+```python
+# api.py
+from ninja_extra import NinjaExtraAPI, throttle
+from ninja_extra.throttling import DynamicRateThrottle
+api = NinjaExtraAPI()
+
+@api.get('/users')
+@throttle(DynamicRateThrottle, scope='burst')
+def get_users(request):
+    return 'foo'
+
+@api.get('/users/<int:id>')
+@throttle(DynamicRateThrottle, scope='sustained')
+def get_user_by_id(request, id: int):
+    return 'foo'
+```
+Here, we dynamically applied `sustained` rates and `burst` rates to `get_users` and `get_user_by_id` respectively

docs/docs/tutorial/throttling.md

@@ -1,59 +1,60 @@
-site_name: Django Ninja Extra
-site_description: Django Ninja Extra - Adds more power to Django Ninja RESTful api library
-site_url: https://eadwincode.github.io/django-ninja-extra/
-repo_name: eadwinCode/django-ninja
-repo_url: https://github.com/eadwinCode/django-ninja-extra
-edit_uri: ''
-
-theme:
-  name: material
-  palette:
-    - media: "(prefers-color-scheme: light)"
-      scheme: default
-      primary: deeppurple
-      accent: deeppurple
-      toggle:
-        icon: material/toggle-switch
-        name: Switch to dark mode
-
-    - media: "(prefers-color-scheme: dark)"
-      scheme: slate
-      primary: blue
-      accent: blue
-      toggle:
-        icon: material/toggle-switch-off-outline
-        name: Switch to light mode
-
-  language: en
-  icon:
-    repo: fontawesome/brands/git-alt
-plugins:
-- search
-- mkdocstrings
-
-nav:
-- Index: index.md
-- APIController:
-  - Index: api_controller/index.md
-  - Controller Routes: api_controller/api_controller_route.md
-  - Controller Permissions: api_controller/api_controller_permission.md
-- Usage:
-  - Quick Tutorial: tutorial/index.md
-  - Authentication: tutorial/authentication.md
-  - Path Parameter: tutorial/path.md
-  - Query Request: tutorial/query.md
-  - Body Request: tutorial/body_request.md
-  - Form Request: tutorial/form.md
-  - Schema: tutorial/schema.md
-  - Pagination: tutorial/pagination.md
-  - Error Handling: tutorial/custom_exception.md
-  - Versioning: tutorial/versioning.md
-  - Testing: tutorial/testing.md
-- Settings: settings.md
-- Dependency Injection: service_module_injector.md
-
-markdown_extensions:
-- markdown_include.include
-- codehilite
-- admonition
-- pymdownx.superfences
+site_name: Django Ninja Extra
+site_description: Django Ninja Extra - Adds more power to Django Ninja RESTful api library
+site_url: https://eadwincode.github.io/django-ninja-extra/
+repo_name: eadwinCode/django-ninja
+repo_url: https://github.com/eadwinCode/django-ninja-extra
+edit_uri: ''
+
+theme:
+  name: material
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: deeppurple
+      accent: deeppurple
+      toggle:
+        icon: material/toggle-switch
+        name: Switch to dark mode
+
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: blue
+      accent: blue
+      toggle:
+        icon: material/toggle-switch-off-outline
+        name: Switch to light mode
+
+  language: en
+  icon:
+    repo: fontawesome/brands/git-alt
+plugins:
+- search
+- mkdocstrings
+
+nav:
+- Index: index.md
+- APIController:
+  - Index: api_controller/index.md
+  - Controller Routes: api_controller/api_controller_route.md
+  - Controller Permissions: api_controller/api_controller_permission.md
+- Usage:
+  - Quick Tutorial: tutorial/index.md
+  - Authentication: tutorial/authentication.md
+  - Path Parameter: tutorial/path.md
+  - Query Request: tutorial/query.md
+  - Body Request: tutorial/body_request.md
+  - Form Request: tutorial/form.md
+  - Schema: tutorial/schema.md
+  - Pagination: tutorial/pagination.md
+  - Error Handling: tutorial/custom_exception.md
+  - Versioning: tutorial/versioning.md
+  - Throttling: tutorial/throttling.md
+  - Testing: tutorial/testing.md
+- Settings: settings.md
+- Dependency Injection: service_module_injector.md
+
+markdown_extensions:
+- markdown_include.include
+- codehilite
+- admonition
+- pymdownx.superfences

docs/mkdocs.yml renamed to mkdocs.yml

@@ -1,6 +1,6 @@
 """Django Ninja Extra - Class Based Utility and more for Django Ninja(Fast Django REST framework)"""
 
-__version__ = "0.15.2"
+__version__ = "0.15.4"
 
 import django
 
@@ -17,7 +17,9 @@
 from ninja_extra.controllers.route import route
 from ninja_extra.dependency_resolver import get_injector, service_resolver
 from ninja_extra.main import NinjaExtraAPI
+from ninja_extra.pagination import paginate
 from ninja_extra.router import Router
+from ninja_extra.throttling import throttle
 
 if django.VERSION < (3, 2):  # pragma: no cover
     default_app_config = "ninja_extra.apps.NinjaExtraConfig"
@@ -42,4 +44,6 @@
     "service_resolver",
     "lazy",
     "Router",
+    "throttle",
+    "paginate",
 ]

ninja_extra/__init__.py

@@ -1,4 +1,4 @@
-from typing import Any, List
+from typing import Any, Dict, List, Optional
 
 from django.conf import settings as django_settings
 from django.test.signals import setting_changed
@@ -16,6 +16,11 @@ def __init__(self, data: dict) -> None:
 NinjaExtra_SETTINGS_DEFAULTS = dict(
     INJECTOR_MODULES=[],
     PAGINATION_CLASS="ninja_extra.pagination.LimitOffsetPagination",
+    THROTTLE_CLASSES=[
+        "ninja_extra.throttling.AnonRateThrottle",
+        "ninja_extra.throttling.UserRateThrottle",
+    ],
+    THROTTLE_RATES={"user": None, "anon": None},
 )
 
 USER_SETTINGS = UserDefinedSettingsMapper(
@@ -32,6 +37,11 @@ class Config:
         "ninja_extra.pagination.LimitOffsetPagination",
     )
     PAGINATION_PER_PAGE: int = Field(100)
+    THROTTLE_RATES: Dict[str, Optional[str]] = Field(
+        {"user": "1000/day", "anon": "100/day"}
+    )
+    THROTTLE_CLASSES: List[Any] = []
+    NUM_PROXIES: Optional[int] = None
     INJECTOR_MODULES: List[Any] = []
 
     @validator("INJECTOR_MODULES", pre=True)
@@ -40,6 +50,12 @@ def pre_injector_module_validate(cls, value: Any) -> Any:
             raise ValueError("Invalid data type")
         return value
 
+    @validator("THROTTLE_CLASSES", pre=True)
+    def pre_throttling_class_validate(cls, value: Any) -> Any:
+        if not isinstance(value, list):
+            raise ValueError("Invalid data type")
+        return value
+
     @validator("PAGINATION_CLASS", pre=True)
     def pre_pagination_class_validate(cls, value: Any) -> Any:
         if isinstance(value, list):