From 5c013da69b66f40b40590da99fb5f1660e95deab Mon Sep 17 00:00:00 2001 From: Barry Warsaw Date: Thu, 23 Jul 2026 11:36:41 -0700 Subject: [PATCH] Require the index to temporarily reserve first-upload project names * 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. --- peps/pep-0694.rst | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) 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.