PEP 694: Require the index to temporarily reserve first-upload project names

peps/pep-0694.rst

@@ -379,11 +379,15 @@ Upon successful session creation, the server returns a ``201 Created`` response.
 include a ``Location`` header containing the same URL as the :ref:`links.session <publishing-session-links>`
 key in the :ref:`response body <publishing-session-response>`.
 
-If a session is created for a project which has no previous release, then the index **MAY** reserve the
-project name before the session is published, however it **MUST NOT** be possible to navigate to that project
-using the "regular" (i.e. :ref:`unstaged <staged-preview>`) access protocols, *until* the stage is published.
-If this first-release stage gets canceled, then the index **SHOULD** delete the project record, as if it were
-never uploaded.
+If a session is created for a project which has no previous release, then the index **MUST** reserve the
+project name when the session is created.  This is a temporary reservation, held only for the life of the
+stage; it exists to prevent a name-claiming race condition at stage publication time, where two different
+clients each create a stage for the first upload of a new project, and the name would otherwise be claimed by
+whichever client happens to publish its stage first.  It **MUST NOT** be possible to navigate to the reserved
+project using the "regular" (i.e. :ref:`unstaged <staged-preview>`) access protocols, *until* the stage is
+published, at which point the reservation becomes a permanent registration of the name.  If this
+first-release stage gets canceled, then the index **SHOULD** delete the project record, as if it were never
+uploaded, releasing the reservation.
 
 A publishing session is **not** bound to the specific credentials that created it.  Instead, every request
 against the session **MUST** be performed by an authenticated principal that is authorized to upload to the
@@ -1832,6 +1836,11 @@ Change History
     Tie file upload session status URL retention to the parent publishing session: while the parent is
     non-terminal the server **SHOULD** keep its file upload session status URLs valid, and once the parent
     terminates they are retained no longer than the parent's status URL.
+  * Require (was: allow) the index to reserve the project name at session creation when the session
+    is for a project with no previous release.  The reservation is temporary (held only for the life
+    of the stage, becoming permanent on publication and released if the stage is canceled) and
+    exists to prevent a name-claiming race condition in which two different clients each create a
+    stage for the first upload of a new project and whichever publishes first would claim the name.
   * Expand the "Why is the project name required" FAQ to note that single-project sessions still improve
     multi-project releases (all projects can be fully staged before a final step publishes each one) and lay a
     foundation for a possible future "publish multiple projects" endpoint.