♻️(backend) simplify roles by returning only the max role

We were returning the list of roles a user has on a document (direct
and inherited). Now that we introduced priority on roles, we are able
to determine what is the max role and return only this one.

This commit also changes the role that is returned for the restricted
reach: we now return None because the role is not relevant in this
case.

Author: sampaccoud

CHANGELOG.md

@@ -85,7 +85,7 @@ and this project adheres to
 
 ## Added
 
-- ✨(backend) include ancestors accesses on document accesses list view # 846
+- ✨(backend) include ancestors accesses on document accesses list view #846
 - ✨(backend) add ancestors links definitions to document abilities #846
 - 🚸(backend) make document search on title accent-insensitive #874
 - 🚩 add homepage feature flag #861
@@ -98,22 +98,20 @@ and this project adheres to
 
 ## Changed
 
+- ♻️(backend) simplify roles by ranking them and return only the max role #846
 - ⚡️(frontend) reduce unblocking time for config #867
 - ♻️(frontend) bind UI with ability access #900
 - ♻️(frontend) use built-in Quote block #908
 
 ## Fixed
 
+- 🐛(backend) fix link definition select options linked to ancestors #846
 - 🐛(nginx) fix 404 when accessing a doc #866
 - 🔒️(drf) disable browsable HTML API renderer #919
 - 🔒(frontend) enhance file download security #889
 - 🐛(backend) race condition create doc #633
 - 🐛(frontend) fix breaklines in custom blocks #908
 
-## Fixed
-
-- 🐛(backend) fix link definition select options linked to ancestors #846
-
 ## [3.1.0] - 2025-04-07
 
 ## Added

src/backend/core/api/serializers.py

@@ -171,7 +171,7 @@ class ListDocumentSerializer(serializers.ModelSerializer):
     is_favorite = serializers.BooleanField(read_only=True)
     nb_accesses_ancestors = serializers.IntegerField(read_only=True)
     nb_accesses_direct = serializers.IntegerField(read_only=True)
-    user_roles = serializers.SerializerMethodField(read_only=True)
+    user_role = serializers.SerializerMethodField(read_only=True)
     abilities = serializers.SerializerMethodField(read_only=True)
 
     class Meta:
@@ -192,7 +192,7 @@ class Meta:
             "path",
             "title",
             "updated_at",
-            "user_roles",
+            "user_role",
         ]
         read_only_fields = [
             "id",
@@ -209,34 +209,36 @@ class Meta:
             "numchild",
             "path",
             "updated_at",
-            "user_roles",
+            "user_role",
         ]
 
-    def get_abilities(self, document) -> dict:
-        """Return abilities of the logged-in user on the instance."""
-        request = self.context.get("request")
+    def to_representation(self, instance):
+        """Precompute once per instance"""
+        paths_links_mapping = self.context.get("paths_links_mapping")
 
-        if request:
-            paths_links_mapping = self.context.get("paths_links_mapping", None)
-            # Retrieve ancestor links from paths_links_mapping (if provided)
-            ancestors_links = (
-                paths_links_mapping.get(document.path[: -document.steplen])
-                if paths_links_mapping
-                else None
+        if paths_links_mapping is not None:
+            links = paths_links_mapping.get(instance.path[: -instance.steplen], [])
+            instance.ancestors_link_definition = choices.get_equivalent_link_definition(
+                links
             )
-            return document.get_abilities(request.user, ancestors_links=ancestors_links)
 
-        return {}
+        return super().to_representation(instance)
 
-    def get_user_roles(self, document):
+    def get_abilities(self, instance) -> dict:
+        """Return abilities of the logged-in user on the instance."""
+        request = self.context.get("request")
+        if not request:
+            return {}
+
+        return instance.get_abilities(request.user)
+
+    def get_user_role(self, instance):
         """
         Return roles of the logged-in user for the current document,
         taking into account ancestors.
         """
         request = self.context.get("request")
-        if request:
-            return document.get_roles(request.user)
-        return []
+        return instance.get_role(request.user) if request else None
 
 
 class DocumentSerializer(ListDocumentSerializer):
@@ -263,7 +265,7 @@ class Meta:
             "path",
             "title",
             "updated_at",
-            "user_roles",
+            "user_role",
         ]
         read_only_fields = [
             "id",
@@ -279,7 +281,7 @@ class Meta:
             "numchild",
             "path",
             "updated_at",
-            "user_roles",
+            "user_role",
         ]
 
     def get_fields(self):

src/backend/core/api/viewsets.py

@@ -443,14 +443,15 @@ def filter_queryset(self, queryset):
         queryset = queryset.annotate_user_roles(user)
         return queryset
 
-    def get_response_for_queryset(self, queryset):
+    def get_response_for_queryset(self, queryset, context=None):
         """Return paginated response for the queryset if requested."""
+        context = context or self.get_serializer_context()
         page = self.paginate_queryset(queryset)
         if page is not None:
-            serializer = self.get_serializer(page, many=True)
+            serializer = self.get_serializer(page, many=True, context=context)
             return self.get_paginated_response(serializer.data)
 
-        serializer = self.get_serializer(queryset, many=True)
+        serializer = self.get_serializer(queryset, many=True, context=context)
         return drf.response.Response(serializer.data)
 
     def list(self, request, *args, **kwargs):
@@ -460,9 +461,6 @@ def list(self, request, *args, **kwargs):
         This method applies filtering based on request parameters using `ListDocumentFilter`.
         It performs early filtering on model fields, annotates user roles, and removes
         descendant documents to keep only the highest ancestors readable by the current user.
-
-        Additional annotations (e.g., `is_highest_ancestor_for_user`, favorite status) are
-        applied before ordering and returning the response.
         """
         user = self.request.user
 
@@ -490,12 +488,6 @@ def list(self, request, *args, **kwargs):
         )
         queryset = queryset.filter(path__in=root_paths)
 
-        # Annotate the queryset with an attribute marking instances as highest ancestor
-        # in order to save some time while computing abilities on the instance
-        queryset = queryset.annotate(
-            is_highest_ancestor_for_user=db.Value(True, output_field=db.BooleanField())
-        )
-
         # Annotate favorite status and filter if applicable as late as possible
         queryset = queryset.annotate_is_favorite(user)
         queryset = filterset.filters["is_favorite"].filter(
@@ -750,7 +742,17 @@ def children(self, request, *args, **kwargs):
 
         queryset = filterset.qs
 
-        return self.get_response_for_queryset(queryset)
+        # Pass ancestors' links paths mapping to the serializer as a context variable
+        # in order to allow saving time while computing abilities on the instance
+        paths_links_mapping = document.compute_ancestors_links_paths_mapping()
+
+        return self.get_response_for_queryset(
+            queryset,
+            context={
+                "request": request,
+                "paths_links_mapping": paths_links_mapping,
+            },
+        )
 
     @drf.decorators.action(
         detail=True,
@@ -809,39 +811,28 @@ def tree(self, request, pk, *args, **kwargs):
         ancestors_links = []
         children_clause = db.Q()
         for ancestor in ancestors:
-            if ancestor.depth < highest_readable.depth:
-                continue
-
-            children_clause |= db.Q(
-                path__startswith=ancestor.path, depth=ancestor.depth + 1
-            )
-
             # Compute cache for ancestors links to avoid many queries while computing
             # abilities for his documents in the tree!
             ancestors_links.append(
                 {"link_reach": ancestor.link_reach, "link_role": ancestor.link_role}
             )
             paths_links_mapping[ancestor.path] = ancestors_links.copy()
 
+            if ancestor.depth < highest_readable.depth:
+                continue
+
+            children_clause |= db.Q(
+                path__startswith=ancestor.path, depth=ancestor.depth + 1
+            )
+
         children = self.queryset.filter(children_clause, deleted_at__isnull=True)
 
         queryset = ancestors.filter(depth__gte=highest_readable.depth) | children
         queryset = queryset.order_by("path")
-        # Annotate if the current document is the highest ancestor for the user
-        queryset = queryset.annotate(
-            is_highest_ancestor_for_user=db.Case(
-                db.When(
-                    path=db.Value(highest_readable.path),
-                    then=db.Value(True),
-                ),
-                default=db.Value(False),
-                output_field=db.BooleanField(),
-            )
-        )
         queryset = queryset.annotate_user_roles(user)
         queryset = queryset.annotate_is_favorite(user)
 
-        # Pass ancestors' links definitions to the serializer as a context variable
+        # Pass ancestors' links paths mapping to the serializer as a context variable
         # in order to allow saving time while computing abilities on the instance
         serializer = self.get_serializer(
             queryset,
@@ -1441,8 +1432,8 @@ def list(self, request, *args, **kwargs):
         except models.Document.DoesNotExist:
             return drf.response.Response([])
 
-        roles = set(document.get_roles(user))
-        if not roles:
+        role = document.get_role(user)
+        if role is None:
             return drf.response.Response([])
 
         ancestors = (
@@ -1460,7 +1451,7 @@ def list(self, request, *args, **kwargs):
             document__in=ancestors.filter(depth__gte=highest_readable.depth)
         )
 
-        is_privileged = bool(roles.intersection(set(choices.PRIVILEGED_ROLES)))
+        is_privileged = role in choices.PRIVILEGED_ROLES
         if is_privileged:
             serializer_class = serializers.DocumentAccessSerializer
         else:

src/backend/core/choices.py

@@ -11,18 +11,18 @@ class PriorityTextChoices(TextChoices):
     """
 
     @classmethod
-    def get_priority(cls, value):
-        """Returns the priority of the given value based on its order in the class."""
+    def get_priority(cls, role):
+        """Returns the priority of the given role based on its order in the class."""
+
         members = list(cls.__members__.values())
-        return members.index(value) + 1 if value in members else 0
+        return members.index(role) + 1 if role in members else 0
 
     @classmethod
     def max(cls, *roles):
         """
         Return the highest-priority role among the given roles, using get_priority().
         If no valid roles are provided, returns None.
         """
-
         valid_roles = [role for role in roles if cls.get_priority(role) is not None]
         if not valid_roles:
             return None
@@ -61,7 +61,6 @@ class LinkReachChoices(PriorityTextChoices):
     )  # Any authenticated user can access the document
     PUBLIC = "public", _("Public")  # Even anonymous users can access the document
 
-
     @classmethod
     def get_select_options(cls, link_reach, link_role):
         """
@@ -110,3 +109,34 @@ def get_select_options(cls, link_reach, link_role):
             reach: sorted(roles, key=LinkRoleChoices.get_priority) if roles else roles
             for reach, roles in result.items()
         }
+
+
+def get_equivalent_link_definition(ancestors_links):
+    """
+    Return the (reach, role) pair with:
+    1. Highest reach
+    2. Highest role among links having that reach
+    """
+    if not ancestors_links:
+        return {"link_reach": None, "link_role": None}
+
+    # 1) Find the highest reach
+    max_reach = max(
+        ancestors_links,
+        key=lambda link: LinkReachChoices.get_priority(link["link_reach"]),
+    )["link_reach"]
+
+    # 2) Among those, find the highest role (ignore role if RESTRICTED)
+    if max_reach == LinkReachChoices.RESTRICTED:
+        max_role = None
+    else:
+        max_role = max(
+            (
+                link["link_role"]
+                for link in ancestors_links
+                if link["link_reach"] == max_reach
+            ),
+            key=LinkRoleChoices.get_priority,
+        )
+
+    return {"link_reach": max_reach, "link_role": max_role}