Address comments from the reviewer

[noissue]

CHANGES/507.feature

@@ -1,3 +1,3 @@
 Added support for pull-through caching. Users can now configure a dedicated distribution and remote
-linked to an external registry without specifying a repository name (upstream name). Pulp downloads
-missing content automatically if requested and acts as a caching proxy.
+linked to an external registry without the need to create and mirror repositories in advance. Pulp
+downloads missing content automatically if requested and acts as a caching proxy.

docs/workflows/host.rst

@@ -123,32 +123,35 @@ Pull-Through Caching
 --------------------
 
 The Pull-Through Caching feature offers an alternative way to host content by leveraging a **remote
-registry** as the source of truth. This eliminates the need for repository synchronization, reducing
-storage overhead, and ensuring up-to-date images. Pulp acts as a **caching proxy** and stores images
-in a local repository.
+registry** as the source of truth. This eliminates the need for in-advance repository
+synchronization because Pulp acts as a **caching proxy** and stores images, after they have been
+pulled by an end client, in a local repository.
 
-Administering the caching::
+Configuring the caching::
 
     # initialize a pull-through remote (the concept of upstream-name is not applicable here)
     REMOTE_HREF=$(http ${BASE_ADDR}/pulp/api/v3/remotes/container/pull-through/ name=docker-cache url=https://registry-1.docker.io | jq -r ".pulp_href")
 
-    # create a specialized distribution linked to the initialized remote
+    # create a pull-through distribution linked to the initialized remote
     http ${BASE_ADDR}/pulp/api/v3/distributions/container/pull-through/ remote=${REMOTE_HREF} name=docker-cache base_path=docker-cache
 
-Downloading content::
+Pulling content::
 
     podman pull localhost:24817/docker-cache/library/busybox
 
-In the example above, the image "busybox" is pulled from the "docker-cache" distribution, acting as
-a transparent caching layer.
+In the example above, the image "busybox" is pulled from *DockerHub* through the "docker-cache"
+distribution, acting as a transparent caching layer.
 
-By incorporating the Pull-Through Caching feature, administrators can **reduce external network
-dependencies**, and ensure a more reliable and responsive container deployment system in production
-environments.
+By incorporating the Pull-Through Caching feature into standard workflows, users **do not need** to
+pre-configure a new repository and sync it to facilitate the retrieval of the actual content. This
+speeds up the whole process of shipping containers from its early management stages to distribution.
+Similarly to on-demand syncing, the feature also **reduces external network dependencies**, and
+ensures a more reliable container deployment system in production environments.
 
 .. note::
-    Pulp creates repositories that maintain a single repository version for user-pulled images.
+    Pulp creates repositories that maintain a single repository version for pulled images.
     Thus, only the latest repository version is retained. For instance, when pulling "debian:10,"
-    a "debian" repository with the "10" tag is established. Subsequent pulls such as "debian:11"
+    a "debian" repository with the "10" tag is created. Subsequent pulls such as "debian:11"
     result in a new repository version that incorporates both tags while removing the previous
-    version. Repositories and their content remain manageable through standard API endpoints.
+    version. Repositories and their content remain manageable through standard Pulp API endpoints.
+    With that, no content can be pushed to these repositories.

pulp_container/app/migrations/0037_create_pull_through_cache_models.py

@@ -1,4 +1,4 @@
-# Generated by Django 4.2.6 on 2023-10-25 20:04
+# Generated by Django 4.2.7 on 2023-12-08 16:14
 
 from django.db import migrations, models
 import django.db.models.deletion
@@ -8,32 +8,45 @@
 class Migration(migrations.Migration):
 
     dependencies = [
-        ('core', '0108_task_versions'),
+        ('core', '0116_alter_remoteartifact_md5_alter_remoteartifact_sha1_and_more'),
         ('container', '0036_containerpushrepository_pending_blobs_manifests'),
     ]
 
     operations = [
         migrations.CreateModel(
-            name='ContainerPullThroughDistribution',
+            name='ContainerPullThroughRemote',
             fields=[
-                ('distribution_ptr', models.OneToOneField(auto_created=True, on_delete=django.db.models.deletion.CASCADE, parent_link=True, primary_key=True, serialize=False, to='core.distribution')),
+                ('remote_ptr', models.OneToOneField(auto_created=True, on_delete=django.db.models.deletion.CASCADE, parent_link=True, primary_key=True, serialize=False, to='core.remote')),
             ],
             options={
-                'permissions': [('manage_roles_containerpullthroughdistribution', 'Can manage role assignments on pull-through cache distribution')],
+                'permissions': [('manage_roles_containerpullthroughremote', 'Can manage role assignments on pull-through container remote')],
                 'default_related_name': '%(app_label)s_%(model_name)s',
             },
-            bases=('core.distribution', pulpcore.app.models.access_policy.AutoAddObjPermsMixin),
+            bases=('core.remote', pulpcore.app.models.access_policy.AutoAddObjPermsMixin),
+        ),
+        migrations.AddField(
+            model_name='containerrepository',
+            name='pending_blobs',
+            field=models.ManyToManyField(to='container.blob'),
+        ),
+        migrations.AddField(
+            model_name='containerrepository',
+            name='pending_manifests',
+            field=models.ManyToManyField(to='container.manifest'),
         ),
         migrations.CreateModel(
-            name='ContainerPullThroughRemote',
+            name='ContainerPullThroughDistribution',
             fields=[
-                ('remote_ptr', models.OneToOneField(auto_created=True, on_delete=django.db.models.deletion.CASCADE, parent_link=True, primary_key=True, serialize=False, to='core.remote')),
+                ('distribution_ptr', models.OneToOneField(auto_created=True, on_delete=django.db.models.deletion.CASCADE, parent_link=True, primary_key=True, serialize=False, to='core.distribution')),
+                ('private', models.BooleanField(default=False, help_text='Restrict pull access to explicitly authorized users. Related distributions inherit this value. Defaults to unrestricted pull access.')),
+                ('description', models.TextField(null=True)),
+                ('namespace', models.ForeignKey(null=True, on_delete=django.db.models.deletion.CASCADE, related_name='container_pull_through_distributions', to='container.containernamespace')),
             ],
             options={
-                'permissions': [('manage_roles_containerpullthroughremote', 'Can manage role assignments on pull-through container remote')],
+                'permissions': [('manage_roles_containerpullthroughdistribution', 'Can manage role assignments on pull-through cache distribution')],
                 'default_related_name': '%(app_label)s_%(model_name)s',
             },
-            bases=('core.remote', pulpcore.app.models.access_policy.AutoAddObjPermsMixin),
+            bases=('core.distribution', pulpcore.app.models.access_policy.AutoAddObjPermsMixin),
         ),
         migrations.AddField(
             model_name='containerdistribution',

pulp_container/app/models.py

@@ -609,6 +609,8 @@ class ContainerRepository(
     manifest_signing_service = models.ForeignKey(
         ManifestSigningService, on_delete=models.SET_NULL, null=True
     )
+    pending_blobs = models.ManyToManyField(Blob)
+    pending_manifests = models.ManyToManyField(Manifest)
 
     class Meta:
         default_related_name = "%(app_label)s_%(model_name)s"
@@ -632,6 +634,15 @@ def finalize_new_version(self, new_version):
         """
         remove_duplicates(new_version)
         validate_repo_version(new_version)
+        self.remove_pending_content(new_version)
+
+    def remove_pending_content(self, repository_version):
+        """Remove pending blobs and manifests when committing the content to the repository."""
+        added_content = repository_version.added(
+            base_version=repository_version.base_version
+        ).values_list("pk")
+        self.pending_blobs.remove(*Blob.objects.filter(pk__in=added_content))
+        self.pending_manifests.remove(*Manifest.objects.filter(pk__in=added_content))
 
 
 class ContainerPushRepository(Repository, AutoAddObjPermsMixin):
@@ -695,6 +706,22 @@ class ContainerPullThroughDistribution(Distribution, AutoAddObjPermsMixin):
 
     TYPE = "pull-through"
 
+    namespace = models.ForeignKey(
+        ContainerNamespace,
+        on_delete=models.CASCADE,
+        related_name="container_pull_through_distributions",
+        null=True,
+    )
+    private = models.BooleanField(
+        default=False,
+        help_text=_(
+            "Restrict pull access to explicitly authorized users. "
+            "Related distributions inherit this value. "
+            "Defaults to unrestricted pull access."
+        ),
+    )
+    description = models.TextField(null=True)
+
     class Meta:
         default_related_name = "%(app_label)s_%(model_name)s"
         permissions = [