✨(api) search users by email (#16)

* ✨(api) search users by email

The front end should be able to search users by email.
To that goal, we added a list method to the users viewset
thus creating the /users/ endpoint.
Results are filtered based on similarity with the query,
based on what preexisted for the /contacts/ endpoint.

* ✅(api) test list users by email

Test search when complete, partial query,
accentuated and capital.
Also, lower similarity threshold for user search by email
as it was too high for some tests to pass.

* 💡(api) improve documentation and test comments

Improve user viewset documentation
and comments describing tests sections

Co-authored-by: aleb_the_flash <45729124+lebaudantoine@users.noreply.github.com>
Co-authored-by: Anthony LC <anthony.le-courric@mail.numerique.gouv.fr>

* 🛂(api) set isAuthenticated as base requirements

Instead of checking permissions or adding decorators
to every viewset, isAuthenticated is set as base requirement.

* 🛂(api) define throttle limits in settings

Use of Djando Rest Framework's throttle options, now set globally
to avoid duplicate code.

* 🩹(api) add email to user serializer

email field added to serializer. Tests modified accordingly.
I added the email field as "read only" to pass tests, but we need to discuss
that point in review.

* 🧱(api) move search logic to queryset

User viewset "list" method was overridden to allow search by email.
This removed the pagination. Instead of manually re-adding pagination at
the end of this method, I moved the search/filter logic to get_queryset,
to leave DRF handle pagination.

* ✅(api) test throttle protection

Test that throttle protection succesfully blocks too many requests.

* 📝(tests) improve tests comment

Fix typos on comments and clarify which setting are tested on test_throttle test
(setting import required disabling pylint false positive error)

Co-authored-by: aleb_the_flash <45729124+lebaudantoine@users.noreply.github.com>

---------

Co-authored-by: aleb_the_flash <45729124+lebaudantoine@users.noreply.github.com>
Co-authored-by: Anthony LC <anthony.le-courric@mail.numerique.gouv.fr>

src/backend/core/api/viewsets.py

@@ -1,13 +1,6 @@
 """API endpoints"""
 from django.contrib.postgres.search import TrigramSimilarity
-from django.core.cache import cache
-from django.db.models import (
-    Func,
-    OuterRef,
-    Q,
-    Subquery,
-    Value,
-)
+from django.db.models import Func, OuterRef, Q, Subquery, Value
 
 from rest_framework import (
     decorators,
@@ -17,11 +10,16 @@ from rest_framework import (
     response,
     viewsets,
 )
+from rest_framework.throttling import UserRateThrottle
 
 from core import models
 
 from . import permissions, serializers
 
+EMAIL_SIMILARITY_THRESHOLD = 0.01
+# TrigramSimilarity threshold is lower for searching email than for names,
+# to improve matching results
+
 
 class NestedGenericViewSet(viewsets.GenericViewSet):
     """
@@ -103,6 +101,22 @@ class Pagination(pagination.PageNumberPagination):
     page_size_query_param = "page_size"
 
 
+class BurstRateThrottle(UserRateThrottle):
+    """
+    Throttle rate for minutes. See DRF section in settings for default value.
+    """
+
+    scope = "burst"
+
+
+class SustainedRateThrottle(UserRateThrottle):
+    """
+    Throttle rate for hours. See DRF section in settings for default value.
+    """
+
+    scope = "sustained"
+
+
 # pylint: disable=too-many-ancestors
 class ContactViewSet(
     mixins.CreateModelMixin,
@@ -116,15 +130,13 @@ class ContactViewSet(
     permission_classes = [permissions.IsOwnedOrPublic]
     queryset = models.Contact.objects.all()
     serializer_class = serializers.ContactSerializer
+    throttle_classes = [BurstRateThrottle, SustainedRateThrottle]
 
     def list(self, request, *args, **kwargs):
         """Limit listed users by a query with throttle protection."""
         user = self.request.user
         queryset = self.filter_queryset(self.get_queryset())
 
-        if not user.is_authenticated:
-            return queryset.none()
-
         # Exclude contacts that:
         queryset = queryset.filter(
             # - belong to another user (keep public and owned contacts)
@@ -150,26 +162,6 @@ class ContactViewSet(
                 .order_by("-similarity")
             )
 
-        # Throttle protection
-        key_base = f"throttle-contact-list-{user.id!s}"
-        key_minute = f"{key_base:s}-minute"
-        key_hour = f"{key_base:s}-hour"
-
-        try:
-            count_minute = cache.incr(key_minute)
-        except ValueError:
-            cache.set(key_minute, 1, 60)
-            count_minute = 1
-
-        try:
-            count_hour = cache.incr(key_hour)
-        except ValueError:
-            cache.set(key_hour, 1, 3600)
-            count_hour = 1
-
-        if count_minute > 20 or count_hour > 150:
-            raise exceptions.Throttled()
-
         serializer = self.get_serializer(queryset, many=True)
         return response.Response(serializer.data)
 
@@ -181,21 +173,52 @@ class ContactViewSet(
 
 
 class UserViewSet(
-    mixins.UpdateModelMixin,
-    viewsets.GenericViewSet,
+    mixins.UpdateModelMixin, viewsets.GenericViewSet, mixins.ListModelMixin
 ):
-    """User ViewSet"""
+    """
+    User viewset for all interactions with user infos and teams.
+
+    GET /api/users/&q=query
+        Return a list of users whose email matches the query. Similarity is
+        calculated using trigram similarity, allowing for partial, case
+        insensitive matches and accentuated queries.
+    """
 
     permission_classes = [permissions.IsSelf]
     queryset = models.User.objects.all().select_related("profile_contact")
     serializer_class = serializers.UserSerializer
+    throttle_classes = [BurstRateThrottle, SustainedRateThrottle]
+    pagination_class = Pagination
+
+    def get_queryset(self):
+        """Limit listed users by a query. Pagination and throttle protection apply."""
+        queryset = self.queryset
+
+        if self.action == "list":
+            # Exclude inactive contacts
+            queryset = queryset.filter(
+                is_active=True,
+            )
+
+            # Search by case-insensitive and accent-insensitive trigram similarity
+            if query := self.request.GET.get("q", ""):
+                similarity = TrigramSimilarity(
+                    Func("email", function="unaccent"),
+                    Func(Value(query), function="unaccent"),
+                )
+                queryset = (
+                    queryset.annotate(similarity=similarity)
+                    .filter(similarity__gte=EMAIL_SIMILARITY_THRESHOLD)
+                    .order_by("-similarity")
+                )
+
+        return queryset
 
     @decorators.action(
         detail=False,
         methods=["get"],
         url_name="me",
         url_path="me",
-        permission_classes=[permissions.IsAuthenticated],
     )
     def get_me(self, request):
         """