Enable API-versioning and allow for both v3 and v4 versions.

This is a tech-preview PR, and will only "turn on" if the
ENABLE_V4_API is set to True in settings.

It will allow urls for /v3/ and /v4/, and reject other versions.

For urlpatterns registered with a `/<str:version>/` slug, views
will be called with a `version=` kwarg.

NOTE: To play this game, plugins will need to insure that all
views accept `**kwargs` first, and then update the patterns in their
`urls.py` to include the version-slug.

See the `/status/` view and serializer(s) for an example of
how to respond based on the incoming request.

NOTE to implementers: **existing tests must pass without changes**
whether the ENABLE flag is True or False. If that isn't the case -
you're doing something wrong.

closes #6462

Co-authored-by: Daniel Alley <dalley@redhat.com>

Author: ggainey

CHANGES/6462.feature

@@ -0,0 +1,9 @@
+Add `/v4/` API to Pulp.
+
+This adds a `/v4/` API path to Pulp, in parallel to the existing `/v3/` path. The two
+are currently (nearly) identical APIs - see the `/pulp/api/v4/status/` ouput for the
+only (current) end-user-visible impact.
+
+This change is primarily setting the stage to allow for future API changes and growth.
+It is in TECH PREVIEW, and is likely to have significant changes happening to it as we
+continue integrating into the rest of the Pulp architecture.

pulp_file/app/tasks/publishing.py

@@ -18,7 +18,7 @@
 log = logging.getLogger(__name__)
 
 
-def publish(manifest, repository_version_pk, checkpoint=False):
+def publish(manifest, repository_version_pk, checkpoint=False, **kwargs):
     """
     Create a Publication based on a RepositoryVersion.
 

pulp_file/app/tasks/synchronizing.py

@@ -111,6 +111,7 @@ def synchronize(remote_pk, repository_pk, mirror, optimize=False, url=None, **kw
         ValueError: If the remote does not specify a URL to sync.
 
     """
+
     remote = Remote.objects.get(pk=remote_pk).cast()
     repository = FileRepository.objects.get(pk=repository_pk)
 

pulp_file/app/viewsets.py

@@ -135,7 +135,7 @@ class FileContentViewSet(SingleArtifactContentUploadViewSet):
         summary="Upload a File synchronously.",
     )
     @action(detail=False, methods=["post"], serializer_class=FileContentUploadSerializer)
-    def upload(self, request):
+    def upload(self, request, **kwargs):
         """Create a File."""
         serializer = self.get_serializer(data=request.data)
         with transaction.atomic():
@@ -258,7 +258,7 @@ class FileRepositoryViewSet(RepositoryViewSet, ModifyRepositoryActionMixin, Role
         responses={202: AsyncOperationResponseSerializer},
     )
     @action(detail=True, methods=["post"], serializer_class=FileRepositorySyncURLSerializer)
-    def sync(self, request, pk):
+    def sync(self, request, pk, **kwargs):
         """
         Synchronizes a repository.
 
@@ -276,16 +276,19 @@ def sync(self, request, pk):
         optimize = serializer.validated_data.get("optimize", True)  # noqa
         if mirror and repository.autopublish:
             raise ValidationError("Cannot use mirror mode with autopublished repository.")
+
+        task_kwargs = {
+            "remote_pk": str(remote.pk),
+            "repository_pk": str(repository.pk),
+            "mirror": mirror,
+            "optimize": optimize,
+        }
+
         result = dispatch(
             tasks.synchronize,
             shared_resources=[remote],
             exclusive_resources=[repository],
-            kwargs={
-                "remote_pk": str(remote.pk),
-                "repository_pk": str(repository.pk),
-                "mirror": mirror,
-                "optimize": optimize,
-            },
+            kwargs=task_kwargs,
         )
         return OperationPostponedResponse(result, request)
 
@@ -559,7 +562,7 @@ class FilePublicationViewSet(PublicationViewSet, RolesMixin):
         description="Trigger an asynchronous task to publish file content.",
         responses={202: AsyncOperationResponseSerializer},
     )
-    def create(self, request):
+    def create(self, request, **kwargs):
         """
         Publishes a repository.
 
@@ -572,13 +575,15 @@ def create(self, request):
         manifest = serializer.validated_data.get("manifest")
         checkpoint = serializer.validated_data.get("checkpoint")
 
-        kwargs = {"repository_version_pk": str(repository_version.pk), "manifest": manifest}
+        task_kwargs = {"repository_version_pk": str(repository_version.pk), "manifest": manifest}
+
         if checkpoint:
-            kwargs["checkpoint"] = True
+            task_kwargs["checkpoint"] = True
+
         result = dispatch(
             tasks.publish,
             shared_resources=[repository_version.repository],
-            kwargs=kwargs,
+            kwargs=task_kwargs,
         )
         return OperationPostponedResponse(result, request)
 
@@ -770,7 +775,7 @@ class FileAlternateContentSourceViewSet(AlternateContentSourceViewSet, RolesMixi
         responses={202: TaskGroupOperationResponseSerializer},
     )
     @action(methods=["post"], detail=True)
-    def refresh(self, request, pk):
+    def refresh(self, request, pk, **kwargs):
         """
         Refresh ACS metadata.
         """
@@ -794,18 +799,18 @@ def refresh(self, request, pk):
             acs_url = (
                 os.path.join(acs.remote.url, acs_path.path) if acs_path.path else acs.remote.url
             )
-
+            task_kwargs = {
+                "remote_pk": str(acs.remote.pk),
+                "repository_pk": str(acs_path.repository.pk),
+                "mirror": False,
+                "url": acs_url,
+            }
             # Dispatching ACS path to own task and assign it to common TaskGroup
             dispatch(
                 tasks.synchronize,
                 shared_resources=[acs.remote, acs],
                 task_group=task_group,
-                kwargs={
-                    "remote_pk": str(acs.remote.pk),
-                    "repository_pk": str(acs_path.repository.pk),
-                    "mirror": False,
-                    "url": acs_url,
-                },
+                kwargs=task_kwargs,
             )
 
         return TaskGroupOperationResponse(task_group, request)

pulpcore/app/contexts.py

@@ -2,12 +2,16 @@
 from contextvars import ContextVar
 
 from asgiref.sync import sync_to_async
+from django.conf import settings
 from django_guid import clear_guid, get_guid, set_guid
 
 _current_task = ContextVar("current_task", default=None)
 _current_user_func = ContextVar("current_user", default=lambda: None)
 _current_domain = ContextVar("current_domain", default=None)
 x_task_diagnostics_var = ContextVar("x_profile_task")
+current_pulp_api_version = ContextVar(
+    "current_pulp_api_version", default=settings.REST_FRAMEWORK.get("DEFAULT_VERSION", "v3")
+)
 
 
 @contextmanager
@@ -45,6 +49,13 @@ def with_domain(domain):
 def with_task_context(task):
     with with_domain(task.pulp_domain), with_guid(task.logging_cid), with_user(task.user):
         task_token = _current_task.set(task)
+        if not task.pulp_api_version:
+            vers_token = current_pulp_api_version.set(
+                settings.REST_FRAMEWORK.get("DEFAULT_VERSION", "v3")
+            )
+        else:
+            vers_token = current_pulp_api_version.set(task.pulp_api_version)
+
         # If this task is being spawned by another task, we should inherit the profile options
         # from the current task.
         diagnostics_token = x_task_diagnostics_var.set(task.profile_options)
@@ -53,6 +64,7 @@ def with_task_context(task):
         finally:
             x_task_diagnostics_var.reset(diagnostics_token)
             _current_task.reset(task_token)
+            current_pulp_api_version.reset(vers_token)
 
 
 @asynccontextmanager
@@ -64,6 +76,12 @@ def _fetch(task):
     domain, user = await _fetch(task)
     with with_domain(domain), with_guid(task.logging_cid), with_user(user):
         task_token = _current_task.set(task)
+        if not task.pulp_api_version:
+            vers_token = current_pulp_api_version.set(
+                settings.REST_FRAMEWORK.get("DEFAULT_VERSION", "v3")
+            )
+        else:
+            vers_token = current_pulp_api_version.set(task.pulp_api_version)
         # If this task is being spawned by another task, we should inherit the profile options
         # from the current task.
         diagnostics_token = x_task_diagnostics_var.set(task.profile_options)
@@ -72,3 +90,4 @@ def _fetch(task):
         finally:
             x_task_diagnostics_var.reset(diagnostics_token)
             _current_task.reset(task_token)
+            current_pulp_api_version.reset(vers_token)

pulpcore/app/find_url.py

@@ -38,11 +38,11 @@ def find_api_root(version="v3", set_domain=True, domain=None, lstrip=False, rewr
     # Some current path-building wants to ignore DOMAIN - make that possible
     if set_domain and settings.DOMAIN_ENABLED:
         if domain:
-            path = f"{api_root}{domain}/api/{version}/"
+            path = rf"{api_root}{domain}/api/{version}/"
         else:
-            path = f"{api_root}{DOMAIN_SLUG}/api/{version}/"
+            path = rf"{api_root}{DOMAIN_SLUG}/api/{version}/"
     else:
-        path = f"{api_root}api/{version}/"
+        path = rf"{api_root}api/{version}/"
     if lstrip:
         return api_root.lstrip("/"), path.lstrip("/")
     else:

pulpcore/app/migrations/0154_task_api_version.py

@@ -0,0 +1,18 @@
+# Generated by Django 5.2.14 on 2026-07-10 23:34
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('core', '0153_taskschedule_pulp_domain_alter_taskschedule_name_and_more'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='task',
+            name='pulp_api_version',
+            field=models.TextField(default='v3'),
+        ),
+    ]

pulpcore/app/models/task.py

@@ -6,6 +6,7 @@
 import traceback
 from gettext import gettext as _
 
+from django.conf import settings
 from django.contrib.postgres.fields import ArrayField, HStoreField
 from django.contrib.postgres.indexes import GinIndex
 from django.core.serializers.json import DjangoJSONEncoder
@@ -143,6 +144,10 @@ class Task(BaseModel, AutoAddObjPermsMixin):
 
     result = models.JSONField(default=None, null=True, encoder=DjangoJSONEncoder)
 
+    pulp_api_version = models.TextField(
+        default=settings.REST_FRAMEWORK.get("DEFAULT_VERSION", "v3")
+    )
+
     @property
     def user(self):
         # These queries were specifically constructed and ordered this way to ensure we have the

pulpcore/app/serializers/status.py

@@ -136,3 +136,12 @@ class StatusSerializer(serializers.Serializer):
     content_settings = ContentSettingsSerializer(help_text=_("Content-app settings"))
 
     domain_enabled = serializers.BooleanField(help_text=_("Is Domains enabled"))
+
+
+class V4StatusSerializer(StatusSerializer):
+    pulp_api_version = serializers.CharField(
+        help_text=_("Pulp API-Version called to generate this status"), default="not-set"
+    )
+    supported_pulp_api_versions = serializers.ListField(
+        help_text=_("Pulp API-Versions currently enabled in this Pulp instance")
+    )

pulpcore/app/serializers/task.py

@@ -1,6 +1,7 @@
 import typing as t
 from gettext import gettext as _
 
+from django.conf import settings
 from drf_spectacular.types import OpenApiTypes
 from drf_spectacular.utils import extend_schema_serializer
 from rest_framework import serializers
@@ -118,6 +119,11 @@ class TaskSerializer(ModelSerializer):
         help_text=_("The result of this task."),
     )
 
+    pulp_api_version = serializers.CharField(
+        help_text=_("The API-version that was invoked when creating the task."),
+        default=settings.REST_FRAMEWORK.get("DEFAULT_VERSION", "v3"),
+    )
+
     def get_worker(self, obj) -> t.Optional[OpenApiTypes.URI]:
         return None
 
@@ -149,13 +155,15 @@ class Meta:
             "created_resource_prns",
             "reserved_resources_record",
             "result",
+            "pulp_api_version",
         )
 
 
 class MinimalTaskSerializer(TaskSerializer):
     class Meta:
         model = models.Task
         fields = ModelSerializer.Meta.fields + (
+            "pulp_api_version",
             "name",
             "state",
             "unblocked_at",