diff --git a/peps/pep-0694.rst b/peps/pep-0694.rst index de05700f085..18e213c6dbb 100644 --- a/peps/pep-0694.rst +++ b/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 ` key in the :ref:`response body `. -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 `) 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 `) 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.