Add staging area for repositories

docs/admin/reference/settings.md

@@ -421,6 +421,26 @@ A JSON object representing the security scheme advertised for the `PulpRemoteUse
 
 Defaults to `{"type": "mutualTLS"}`, which represents x509 certificate based authentication.
 
+### STAGING\_AUTOCOMMIT\_DELAY\_SECONDS
+
+Time in seconds from the first staged content until a repository with autocommit enabled becomes
+eligible for a commit.
+The scheduler's scan interval is separate; this setting does not control how often repositories
+are checked.
+
+Defaults to `300` seconds.
+
+### STAGING\_AUTOCOMMIT\_SCAN\_INTERVAL\_SECONDS
+
+How often, in seconds, the scheduled task checks for repositories whose autocommit deadline has
+passed and dispatches their commit tasks.
+This is separate from `STAGING_AUTOCOMMIT_DELAY_SECONDS`, which determines when staged content first
+becomes eligible for a commit.
+A repository may wait almost one scan interval after its deadline before the scanner sees it.
+Worker scheduling, task pickup, and waiting for the repository lock can add more time.
+
+Defaults to `60` seconds.
+
 ### TASK\_DIAGNOSTICS
 
 When enabled, users are allowed to request various diagnostics for analysis by a developer.

docs/user/guides/stage-repository-content.md

@@ -0,0 +1,102 @@
+# Manage Repository Staging
+
+A repository staging area holds content associated with a repository before it belongs to a repository version.
+
+Staged content is not served by a distribution and does not trigger checks and operations that creating a repository version would.
+Because it doesn't have those checks, it can be used to avoid repository version creation overhead.
+
+You can inspect the staging area, commit its content into a new repository version, or discard it.
+
+These examples use the file plugin, but staging works with repositories from any plugin.
+Replace `/repositories/file/file/` with your plugin's repository endpoint.
+
+The commands use HTTPie and the `admin` user.
+Set `PULP_API_URL` to the API base URL, including its port and version, without a trailing slash.
+Set `PULP_PASSWORD` to the `admin` password and `REPOSITORY_NAME` to the name of the new repository.
+
+## Enable Staging
+
+Set `staging_enabled` when creating a repository.
+It defaults to `false`.
+
+```bash
+http --auth "admin:$PULP_PASSWORD" POST "$PULP_API_URL/repositories/file/file/" \
+  name="$REPOSITORY_NAME" staging_enabled:=true
+```
+
+The staging endpoints return `404` while staging is disabled for the repository.
+Set `REPOSITORY_ID` to the ID in the returned `pulp_href` before using the following commands.
+
+## Commit Staged Content Automatically
+
+Set `staging_autocommit` on a repository with staging enabled to commit staged content on a schedule.
+It defaults to `false`.
+
+```bash
+http --auth "admin:$PULP_PASSWORD" PATCH \
+  "$PULP_API_URL/repositories/file/file/${REPOSITORY_ID}/" \
+  staging_autocommit:=true
+```
+
+The first content staged after autocommit is enabled starts the delay set by
+[`STAGING_AUTOCOMMIT_DELAY_SECONDS`](site:pulpcore/docs/admin/reference/settings/#staging_autocommit_delay_seconds).
+Staging more content does not postpone that deadline.
+A separate scheduled task checks for expired deadlines at the interval set by
+[`STAGING_AUTOCOMMIT_SCAN_INTERVAL_SECONDS`](site:pulpcore/docs/admin/reference/settings/#staging_autocommit_scan_interval_seconds)
+and dispatches a commit task for each ready repository.
+The commit task may wait for other tasks holding the repository lock.
+
+Autocommit only affects content already placed in staging; enabling it does not change the file
+upload endpoint.
+A manual commit or restore clears the pending deadline.
+If a commit fails, the staged content and deadline remain available for another attempt.
+
+## Inspect Staged Content
+
+Use the repository's `pulp_href` followed by `staging/` to list staged content URLs.
+The list is paginated with `limit` and `offset`.
+An empty list returns `{"count": 0, "next": null, "previous": null, "results": []}`.
+`HEAD` on `staging/` returns `200` when staging is enabled.
+
+To retrieve one staged content unit by path, append its `relative_path` to `staging/`.
+Set `RELATIVE_PATH` to the staged content unit's relative path before using the path commands.
+
+```bash
+# List staged content URLs.
+http --auth "admin:$PULP_PASSWORD" GET \
+  "$PULP_API_URL/repositories/file/file/${REPOSITORY_ID}/staging/" \
+  limit==20 offset==0
+
+# Check whether staging is enabled.
+http --auth "admin:$PULP_PASSWORD" HEAD \
+  "$PULP_API_URL/repositories/file/file/${REPOSITORY_ID}/staging/"
+
+# Retrieve content at a relative path, or check whether it exists.
+http --auth "admin:$PULP_PASSWORD" GET \
+  "$PULP_API_URL/repositories/file/file/${REPOSITORY_ID}/staging/${RELATIVE_PATH}/"
+http --auth "admin:$PULP_PASSWORD" HEAD \
+  "$PULP_API_URL/repositories/file/file/${REPOSITORY_ID}/staging/${RELATIVE_PATH}/"
+```
+
+The response contains the content unit's `pulp_href` and plugin-specific fields.
+Nested paths remain part of `relative_path`; URL-encode reserved characters.
+`GET` and `HEAD` return `404` when the path is not staged.
+
+## Commit or Discard Staged Content
+
+Commit staged content to create a new repository version when the content changes, or discard all staged content without creating a version:
+
+```bash
+# Commit staged content.
+http --auth "admin:$PULP_PASSWORD" POST \
+  "$PULP_API_URL/repositories/file/file/${REPOSITORY_ID}/staging/?action=commit"
+
+# Discard staged content.
+http --auth "admin:$PULP_PASSWORD" POST \
+  "$PULP_API_URL/repositories/file/file/${REPOSITORY_ID}/staging/?action=restore"
+```
+
+If staging contains content, either action returns `202 Accepted` with a task URL in the `task` field.
+
+Wait for that task to complete before checking the repository version or staging area.
+If staging is empty, either action returns `204 No Content` and creates no task.

docs/user/guides/upload-publish.md

@@ -16,6 +16,8 @@ the content from.
 You can automatically associate newly uploaded content with a Repository when using the
 `/pulp/api/v3/content/<plugin_name>/<content_type>/` API by passing the `repository reference`.
 
+For the repository staging API, see [Manage Repository Staging](site:pulpcore/docs/user/guides/stage-repository-content/).
+
 ## Chunked Uploads
 
 For large file uploads, Pulp provides an [Uploads API](site:pulpcore/restapi/#tag/Uploads). To begin

pulp_file/app/viewsets.py

@@ -207,14 +207,20 @@ class FileRepositoryViewSet(RepositoryViewSet, ModifyRepositoryActionMixin, Role
                 ],
             },
             {
-                "action": ["modify"],
+                "action": ["modify", "staging_post"],
                 "principal": "authenticated",
                 "effect": "allow",
                 "condition": [
                     "has_model_or_domain_or_obj_perms:file.modify_filerepository",
                     "has_model_or_domain_or_obj_perms:file.view_filerepository",
                 ],
             },
+            {
+                "action": ["staging", "staging_head", "staging_path", "staging_path_head"],
+                "principal": "authenticated",
+                "effect": "allow",
+                "condition": ["has_model_or_domain_or_obj_perms:file.view_filerepository"],
+            },
             {
                 "action": ["list_roles", "add_role", "remove_role"],
                 "principal": "authenticated",