docs: add cache support documentation

- Added cache_support.rst
- Updated 'index.rst' to include the new page in the toctree
- Documented related cache settings in settings.rst

Author: juanbailon

docs/cache_support.rst

@@ -0,0 +1,65 @@
+Cache Support
+==============
+
+SimpleJWT provides optional cache support for improving performance. 
+Currently, caching is available for:
+
+- Blacklisted refresh tokens
+- Blacklisted token families
+
+To enable caching in SimpleJWT, you must first configure Django's ``CACHES`` setting:
+
+.. code-block:: python
+
+    CACHES = {
+        "default": {
+            "BACKEND": "django.core.cache.backends.locmem.LocMemCache",
+            "LOCATION": "unique-name",
+        },
+        "redis": {
+            "BACKEND": "django_redis.cache.RedisCache",
+            "LOCATION": "redis://127.0.0.1:6379/0",
+            "OPTIONS": {
+                "CLIENT_CLASS": "django_redis.client.DefaultClient",
+            }
+        }
+    }
+
+In this example, two cache backends are defined. You can choose which one to use by 
+setting the ``SJWT_CACHE_NAME`` option in your SimpleJWT configuration. For this case, 
+it could be either `"default"` or `"redis"`.
+
+.. Note::
+    Ensure that your Django `CACHES` setting includes a cache matching the alias 
+    defined by `SJWT_CACHE_NAME`.
+
+
+Blacklist Cache
+----------------
+
+When enabled via the appropriate settings, blacklisted refresh tokens and token families
+will be cached. This reduces the number of database queries when verifying whether a token
+or family is blacklisted.
+
+.. code-block:: python
+
+    SIMPLE_JWT = {
+        ...
+
+        "SJWT_CACHE_NAME": "default",
+        "CACHE_BLACKLISTED_REFRESH_TOKENS": True,
+        "CACHE_BLACKLISTED_FAMILIES": True,
+        "CACHE_TTL_BLACKLISTED_REFRESH_TOKENS": 3600, #time in seconds
+        "CACHE_TTL_BLACKLISTED_FAMILIES": 3600, #time in seconds
+        "CACHE_KEY_PREFIX_BLACKLISTED_REFRESH_TOKENS": "sjwt_brt",
+        "CACHE_KEY_PREFIX_BLACKLISTED_FAMILIES": "sjwt_btf",
+
+        ...
+    }
+
+
+Cache keys follow this format:
+
+- Refresh token: ``sjwt_brt:<jti>``
+- Token family: ``sjwt_btf:<family_id>``
+

docs/index.rst

@@ -53,6 +53,7 @@ Contents
     blacklist_app
     family_app
     stateless_user_authentication
+    cache_support
     development_and_contributing
     drf_yasg_integration
     rest_framework_simplejwt

docs/settings.rst

@@ -34,6 +34,14 @@ Some of Simple JWT's behavior can be customized through settings variables in
       "JWK_URL": None,
       "LEEWAY": 0,
 
+      "SJWT_CACHE_NAME": "default",
+      "CACHE_BLACKLISTED_REFRESH_TOKENS": False,
+      "CACHE_BLACKLISTED_FAMILIES": False,
+      "CACHE_TTL_BLACKLISTED_REFRESH_TOKENS": 3600,  # time is seconds
+      "CACHE_TTL_BLACKLISTED_FAMILIES": 3600,  # time in seconds
+      "CACHE_KEY_PREFIX_BLACKLISTED_REFRESH_TOKENS": "sjwt_brt",
+      "CACHE_KEY_PREFIX_BLACKLISTED_FAMILIES": "sjwt_btf",
+
       "AUTH_HEADER_TYPES": ("Bearer",),
       "AUTH_HEADER_NAME": "HTTP_AUTHORIZATION",
       "USER_ID_FIELD": "id",
@@ -222,6 +230,47 @@ integer for seconds or a ``datetime.timedelta``. Please reference
 https://pyjwt.readthedocs.io/en/latest/usage.html#expiration-time-claim-exp
 for more information.
 
+``SJWT_CACHE_NAME``
+---------------------
+
+Specifies the Django cache alias to use. This must match a defined entry
+in Django's ``CACHES`` setting.
+
+Learn more about :doc:`/cache_support`.
+
+``CACHE_BLACKLISTED_REFRESH_TOKENS``
+--------------------------------------
+
+When set to ``True``, enables caching of blacklisted refresh tokens.
+Blacklisted refresh token entries will be cached for a period defined
+by ``CACHE_TTL_BLACKLISTED_REFRESH_TOKENS``.
+
+``CACHE_BLACKLISTED_FAMILIES``
+--------------------------------
+
+When set to ``True``, enables caching of blacklisted token families.
+Blacklisted family entries will be cached for a period defined 
+by ``CACHE_TTL_BLACKLISTED_FAMILIES``.
+
+``CACHE_TTL_BLACKLISTED_REFRESH_TOKENS``
+------------------------------------------
+
+Time-to-live (TTL) in seconds for cached refresh token blacklist entries.
+
+``CACHE_TTL_BLACKLISTED_FAMILIES``
+------------------------------------
+
+Time-to-live (TTL) in seconds for cached token family blacklist entries.
+
+``CACHE_KEY_PREFIX_BLACKLISTED_REFRESH_TOKENS``
+-------------------------------------------------
+
+Prefix used for cache keys when storing blacklisted refresh tokens.
+
+``CACHE_KEY_PREFIX_BLACKLISTED_FAMILIES``
+-------------------------------------------
+
+Prefix used for cache keys when storing blacklisted token families.
 
 ``AUTH_HEADER_TYPES``
 ---------------------