Add base_version filter to compute net content diffs across arbitrary repository versions

This PR adds a base_version filter to the content viewset that lets repository_version_added
and repository_version_removed compute the net content diff between two arbitray (non-adjacent)
repository versions, rather than only the single-step diff against the immediate predecessor.
Benchmarks on a synthetic 200k-unit system with 1000-unit diffs between repo versions show
that implementing a subquery vs inlined-parameter form is ~12-13x faster, with the query going
from 1471ms -> 116ms for a 50k/50k repo version pair and 6802ms -> 521ms for a 199k/199k repo
version pair, qith query planning time dropping from 72ms -> 1.6ms.

When base_version is omitted, behavior is unchanged (single-step diff), preserving backward
compatibility. If base_version is provided without repository_version_added or
repository_version_removed, nothing happens.

Closes #7831

Assisted by: Claude Opus 4.8

Author: Andrew Cheng

CHANGES/7831.feature

@@ -0,0 +1,4 @@
+Added an optional ``base_version`` filter to the content list endpoints. When combined with
+``repository_version_added`` or ``repository_version_removed``, it returns the net set of content
+added or removed between two arbitrary repository versions instead of only the single-step
+difference against the filtered version's immediate predecessor.

pulpcore/app/models/repository.py

@@ -1000,13 +1000,26 @@ def get_content(self, content_qs=None):
         content_ids = self.content_ids
         if len(content_ids) >= 65535:
             # Workaround for PostgreSQL's limit on the number of parameters in a query
-            content_ids = (
-                RepositoryVersion.objects.filter(pk=self.pk)
-                .annotate(cids=Func(F("content_ids"), function="unnest"))
-                .values_list("cids", flat=True)
-            )
+            content_ids = self.content_ids_subquery()
         return content_qs.filter(pk__in=content_ids)
 
+    def content_ids_subquery(self):
+        """
+        Return this version's ``content_ids`` as a database-side ``unnest`` subquery.
+
+        Using a subquery keeps the content unit UUIDs inside PostgreSQL instead of loading the
+        whole array into Python and passing each UUID as a bound query parameter. This avoids the
+        per-query parameter limit and the memory/serialization cost for large repository versions.
+
+        Returns:
+            django.db.models.QuerySet: A values queryset yielding the content unit UUIDs.
+        """
+        return (
+            RepositoryVersion.objects.filter(pk=self.pk)
+            .annotate(cids=Func(F("content_ids"), function="unnest"))
+            .values_list("cids", flat=True)
+        )
+
     @property
     def content(self):
         """
@@ -1119,8 +1132,8 @@ def added(self, base_version=None):
         if not base_version:
             return Content.objects.filter(version_memberships__version_added=self)
 
-        return Content.objects.filter(pk__in=self.content_ids).exclude(
-            pk__in=base_version.content_ids
+        return Content.objects.filter(pk__in=self.content_ids_subquery()).exclude(
+            pk__in=base_version.content_ids_subquery()
         )
 
     def removed(self, base_version=None):
@@ -1134,8 +1147,8 @@ def removed(self, base_version=None):
         if not base_version:
             return Content.objects.filter(version_memberships__version_removed=self)
 
-        return Content.objects.filter(pk__in=base_version.content_ids).exclude(
-            pk__in=self.content_ids
+        return Content.objects.filter(pk__in=base_version.content_ids_subquery()).exclude(
+            pk__in=self.content_ids_subquery()
         )
 
     def contains(self, content):

pulpcore/app/viewsets/content.py

@@ -23,6 +23,7 @@
     ContentAddedRepositoryVersionFilter,
     ContentRemovedRepositoryVersionFilter,
     ContentRepositoryVersionFilter,
+    RepositoryVersionBaseFilter,
 )
 
 
@@ -125,6 +126,10 @@ class ContentFilter(BaseFilterSet):
             Return Content which was added in this repository version.
         repository_version_removed:
             Return Content which was removed from this repository version.
+        base_version:
+            When combined with repository_version_added / repository_version_removed, compute the
+            net difference relative to this base repository version instead of the filtered
+            version's immediate predecessor. Has no effect on its own.
         orphaned_for:
             Return Content which has been orphaned for a given number of minutes;
             -1 uses ORPHAN_PROTECTION_TIME value.
@@ -135,6 +140,7 @@ class ContentFilter(BaseFilterSet):
     repository_version = ContentRepositoryVersionFilter()
     repository_version_added = ContentAddedRepositoryVersionFilter()
     repository_version_removed = ContentRemovedRepositoryVersionFilter()
+    base_version = RepositoryVersionBaseFilter()
     orphaned_for = OrphanedFilter(
         help_text="Minutes Content has been orphaned for. -1 uses ORPHAN_PROTECTION_TIME."
     )

pulpcore/app/viewsets/custom_filters.py

@@ -162,6 +162,53 @@ def filter(self, qs, value):
         """
         raise NotImplementedError()
 
+    def get_base_version(self, field_name="base_version"):
+        """
+        Resolve the companion ``base_version`` filter, if the request supplied one.
+
+        The added/removed filters use this to diff against an *arbitrary* base repository
+        version instead of the filtered version's immediate predecessor.
+
+        Args:
+            field_name (string): The name of the companion base-version filter on the filterset.
+
+        Returns:
+            pulpcore.app.models.RepositoryVersion or None: The resolved base version, or None
+            when no base version was supplied.
+        """
+        if self.parent is None:
+            return None
+        base_value = self.parent.form.cleaned_data.get(field_name)
+        if not base_value:
+            return None
+        return self.get_repository_version(base_value)
+
+
+class RepositoryVersionBaseFilter(RepoVersionHrefPrnFilter):
+    """
+    Companion filter that designates the base repository version for
+    ``repository_version_added`` / ``repository_version_removed`` diffs.
+
+    On its own this filter does not alter the queryset. It is consumed by the added/removed
+    filters to compute the net difference between two arbitrary repository versions, rather than
+    the single-step difference against the filtered version's immediate predecessor.
+    """
+
+    def __init__(self, *args, **kwargs):
+        kwargs.setdefault(
+            "help_text",
+            _(
+                "Repository Version referenced by HREF/PRN to use as the base for "
+                "repository_version_added / repository_version_removed. When set, added/removed "
+                "content is computed relative to this version instead of the immediate predecessor."
+            ),
+        )
+        super().__init__(*args, **kwargs)
+
+    def filter(self, qs, value):
+        # No-op on its own; the value is consumed by the added/removed filters.
+        return qs
+
 
 class RepositoryVersionFilter(RepoVersionHrefPrnFilter):
     """
@@ -251,7 +298,7 @@ def filter(self, qs, value):
             return qs
 
         repo_version = self.get_repository_version(value)
-        return qs.filter(pk__in=repo_version.added())
+        return qs.filter(pk__in=repo_version.added(base_version=self.get_base_version()))
 
 
 class ContentRemovedRepositoryVersionFilter(RepoVersionHrefPrnFilter):
@@ -273,7 +320,7 @@ def filter(self, qs, value):
             return qs
 
         repo_version = self.get_repository_version(value)
-        return qs.filter(pk__in=repo_version.removed())
+        return qs.filter(pk__in=repo_version.removed(base_version=self.get_base_version()))
 
 
 class CharInFilter(BaseInFilter, CharFilter):

pulpcore/tests/functional/api/using_plugin/test_repo_versions.py

@@ -188,6 +188,82 @@ def test_add_remove_content(
     assert latest_version.content_summary.removed == {}
 
 
+@pytest.fixture
+def file_repo_three_versions(
+    file_bindings,
+    file_repository_factory,
+    file_9_contents,
+    monitor_task,
+):
+    """Build a repo with three versions whose diffs span more than one step.
+
+    Using the content units "A" through "E", the versions end up as::
+
+        v1: add A, B, C      -> present {A, B, C}
+        v2: add D, remove A  -> present {B, C, D}
+        v3: add E, remove B  -> present {C, D, E}
+
+    So a diff between the non-adjacent versions v1 and v3 differs from the single-step diff at v3.
+    """
+    repo = file_repository_factory()
+    contents = file_9_contents
+
+    def modify(add=(), remove=()):
+        body = {
+            "add_content_units": [contents[name].pulp_href for name in add],
+            "remove_content_units": [contents[name].pulp_href for name in remove],
+        }
+        monitor_task(file_bindings.RepositoriesFileApi.modify(repo.pulp_href, body).task)
+        return file_bindings.RepositoriesFileApi.read(repo.pulp_href).latest_version_href
+
+    v1 = modify(add=["A", "B", "C"])
+    v2 = modify(add=["D"], remove=["A"])
+    v3 = modify(add=["E"], remove=["B"])
+    return repo, v1, v2, v3
+
+
+def _relative_paths(list_response):
+    return {content.relative_path for content in list_response.results}
+
+
+@pytest.mark.parallel
+def test_repository_version_added_base_version(file_bindings, file_repo_three_versions):
+    """``base_version`` turns ``repository_version_added`` into a net diff between two versions."""
+    _, v1, v2, v3 = file_repo_three_versions
+
+    # Without base_version: single-step diff against the immediate predecessor (v2 -> v3).
+    single_step = file_bindings.ContentFilesApi.list(repository_version_added=v3)
+    assert _relative_paths(single_step) == {"E"}
+
+    # With base_version=v1: net content in v3 but not in v1 => {C, D, E} - {A, B, C}.
+    net = file_bindings.ContentFilesApi.list(repository_version_added=v3, base_version=v1)
+    assert _relative_paths(net) == {"D", "E"}
+
+
+@pytest.mark.parallel
+def test_repository_version_removed_base_version(file_bindings, file_repo_three_versions):
+    """``base_version`` turns ``repository_version_removed`` into a net diff across versions."""
+    _, v1, v2, v3 = file_repo_three_versions
+
+    # Without base_version: single-step diff against the immediate predecessor (v2 -> v3).
+    single_step = file_bindings.ContentFilesApi.list(repository_version_removed=v3)
+    assert _relative_paths(single_step) == {"B"}
+
+    # With base_version=v1: net content in v1 but not in v3 => {A, B, C} - {C, D, E}.
+    net = file_bindings.ContentFilesApi.list(repository_version_removed=v3, base_version=v1)
+    assert _relative_paths(net) == {"A", "B"}
+
+
+@pytest.mark.parallel
+def test_base_version_ignored_without_added_or_removed(file_bindings, file_repo_three_versions):
+    """``base_version`` has no effect unless paired with added/removed filters."""
+    _, v1, v2, v3 = file_repo_three_versions
+
+    present = file_bindings.ContentFilesApi.list(repository_version=v3)
+    present_with_base = file_bindings.ContentFilesApi.list(repository_version=v3, base_version=v1)
+    assert _relative_paths(present_with_base) == _relative_paths(present) == {"C", "D", "E"}
+
+
 @pytest.mark.parallel
 def test_add_remove_repo_version(
     file_bindings,