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

Author: ggainey

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,20 @@ 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.")
-        result = dispatch(
-            tasks.synchronize,
-            shared_resources=[remote],
-            exclusive_resources=[repository],
-            kwargs={
+
+        task_kwargs = {
                 "remote_pk": str(remote.pk),
                 "repository_pk": str(repository.pk),
                 "mirror": mirror,
                 "optimize": optimize,
-            },
+            }
+        task_kwargs.update(kwargs)
+
+        result = dispatch(
+            tasks.synchronize,
+            shared_resources=[remote],
+            exclusive_resources=[repository],
+            kwargs=task_kwargs,
         )
         return OperationPostponedResponse(result, request)
 
@@ -559,7 +563,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 +576,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}
+        task_kwargs.update(kwargs)
+
         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 +776,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 +800,19 @@ 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,
+                }
+            task_kwargs.update(kwargs)
             # 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

@@ -4,10 +4,15 @@
 from asgiref.sync import sync_to_async
 from django_guid import clear_guid, get_guid, set_guid
 
+from pulpcore.app.settings import REST_FRAMEWORK
+
 _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_version = ContextVar(
+    "current_pulp_version", default=REST_FRAMEWORK.get("DEFAULT_VERSION", "v3")
+)
 
 
 @contextmanager
@@ -45,6 +50,11 @@ 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.version:
+            vers_token = _current_pulp_version.set(REST_FRAMEWORK.get("DEFAULT_VERSION", "v3"))
+        else:
+            vers_token = _current_pulp_version.set(task.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 +63,7 @@ def with_task_context(task):
         finally:
             x_task_diagnostics_var.reset(diagnostics_token)
             _current_task.reset(task_token)
+            _current_pulp_version.reset(vers_token)
 
 
 @asynccontextmanager
@@ -64,6 +75,10 @@ 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.version:
+            vers_token = _current_pulp_version.set(REST_FRAMEWORK.get("DEFAULT_VERSION", "v3"))
+        else:
+            vers_token = _current_pulp_version.set(task.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 +87,4 @@ def _fetch(task):
         finally:
             x_task_diagnostics_var.reset(diagnostics_token)
             _current_task.reset(task_token)
+            _current_pulp_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/0152_task_api_version.py

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

pulpcore/app/models/task.py

@@ -23,6 +23,7 @@
 from pulpcore.app.models.fields import EncryptedJSONField
 from pulpcore.app.models.status import AppStatus
 from pulpcore.app.role_util import get_users_with_perms
+from pulpcore.app.settings import REST_FRAMEWORK
 from pulpcore.app.util import get_domain_pk
 from pulpcore.constants import TASK_CHOICES, TASK_INCOMPLETE_STATES, TASK_STATES
 from pulpcore.exceptions import exception_to_dict
@@ -143,6 +144,8 @@ class Task(BaseModel, AutoAddObjPermsMixin):
 
     result = models.JSONField(default=None, null=True, encoder=DjangoJSONEncoder)
 
+    version = models.TextField(default=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):
+    api_version = serializers.CharField(
+        help_text=_("API-Version called to generate this status"), default="not-set"
+    )
+    supported_api_versions = serializers.ListField(
+        help_text=_("API-Versions currently enabled in this Pulp instance")
+    )

pulpcore/app/serializers/task.py

@@ -16,6 +16,7 @@
     TaskGroupStatusCountField,
     fields,
 )
+from pulpcore.app.settings import REST_FRAMEWORK
 from pulpcore.app.util import get_prn, reverse
 from pulpcore.constants import TASK_STATES
 
@@ -118,6 +119,11 @@ class TaskSerializer(ModelSerializer):
         help_text=_("The result of this task."),
     )
 
+    version = serializers.CharField(
+        help_text=_("The API-version that was invoked when creating the task."),
+        default=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",
+            "version",
         )
 
 
 class MinimalTaskSerializer(TaskSerializer):
     class Meta:
         model = models.Task
         fields = ModelSerializer.Meta.fields + (
+            "version",
             "name",
             "state",
             "unblocked_at",

pulpcore/app/settings.py

@@ -47,6 +47,8 @@
     ],
 )
 
+ENABLE_V4_API = False
+
 # Build paths inside the project like this: BASE_DIR / ...
 BASE_DIR = Path(__file__).absolute().parent
 
@@ -179,7 +181,6 @@
 ]
 
 WSGI_APPLICATION = "pulpcore.app.wsgi.application"
-
 REST_FRAMEWORK = {
     "URL_FIELD_NAME": "pulp_href",
     "DEFAULT_FILTER_BACKENDS": ("pulpcore.filters.PulpFilterBackend",),
@@ -194,6 +195,11 @@
     "DEFAULT_VERSIONING_CLASS": "rest_framework.versioning.URLPathVersioning",
     "DEFAULT_SCHEMA_CLASS": "pulpcore.openapi.PulpAutoSchema",
 }
+ENABLE_V4_API = True
+if ENABLE_V4_API:
+    REST_FRAMEWORK["ALLOWED_VERSIONS"] = ["v3", "v4"]
+    REST_FRAMEWORK["DEFAULT_VERSION"] = "v3"
+
 
 # Password validation
 # https://docs.djangoproject.com/en/3.2/ref/settings/#auth-password-validators
@@ -653,13 +659,13 @@ def otel_middleware_hook(settings):
     ALLOWED_CONTENT_CHECKSUMS
 )
 
+# protocol://host:port/{API_ROOT}{domain}/api/{version}/
+# All of the below are DEPRECATED, and should be replaced by calling
+# pulpcore.plugin.find_url.find_api_root() (q.v.)
 if settings.API_ROOT_REWRITE_HEADER:
     api_root = "/<path:api_root>/"
 else:
     api_root = settings.API_ROOT
-# protocol://host:port/{API_ROOT}{domain}/api/{version}/
-# All of the below are DEPRECATED, and should be replaced by calling
-# pulpcore.plugin.find_url.find_api_root() (q.v.)
 settings.set("V3_API_ROOT", api_root + "api/v3/")  # Not user configurable
 settings.set("V3_DOMAIN_API_ROOT", api_root + "<slug:pulp_domain>/api/v3/")
 settings.set("V3_API_ROOT_NO_FRONT_SLASH", settings.V3_API_ROOT.lstrip("/"))