Session status retention and other clarifications

Author: warsaw

peps/pep-0694.rst

@@ -790,9 +790,12 @@ Publishing Session Cancellation
 
 To cancel a publishing session, a client issues a ``DELETE`` request to the ``session`` :ref:`link
 <publishing-session-links>` given in the :ref:`session creation response body <publishing-session-response>`.
-The server then marks the session as ``canceled``, and **SHOULD** purge any data that was uploaded as part of
-that session.  Future attempts to access that session URL or any of the publishing session URLs **MUST**
-return a ``404 Not Found``.
+The server then marks the session as ``canceled`` and **SHOULD** purge any data that was uploaded as part of
+that session.  Once that data is purged, the session's action and data-bearing URLs -- ``links.upload``,
+``links.publish``, ``links.extend``, ``links.stage``, and the individual file URLs -- **SHOULD** become
+unavailable and **MAY** return ``404 Not Found``.  The session status URL (``links.session``) is instead
+retained as described in :ref:`publishing-session-retention`: it continues to report the ``canceled`` status
+for an index-specific period before it too **MAY** return ``404 Not Found``.
 
 Cancellation is only permitted while the session is :ref:`open or in the error state
 <publishing-session-states>`.  If the session is in the ``processing`` state (i.e. because a deferred
@@ -820,6 +823,31 @@ The server will respond to this ``GET`` request with the same :ref:`publishing s
 any changes to ``status``, ``expires-at``, or ``files`` reflected.
 
 
+.. _publishing-session-retention:
+
+Session Status Retention
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A session status URL is not guaranteed to remain valid indefinitely.  Once a session reaches a terminal state
+-- ``published`` or ``canceled`` -- the server **SHOULD** continue to serve its :ref:`status URL
+<publishing-session-status>`, reporting the terminal ``status``, for an index-specific retention period, so
+that clients can reliably observe the final outcome of a session they did not watch to completion.  After that
+retention period elapses, the server **MAY** return ``404 Not Found`` for the status URL.  The length of the
+retention period is left to the index, but **SHOULD** be long enough to let a client that initiated or
+contributed to the session learn its outcome.
+
+This retention applies only to the session *status*; the data-bearing and action URLs for a terminated session
+(for example ``links.stage`` and the individual file URLs) may become unavailable as soon as their underlying
+data is no longer needed, as described for :ref:`cancellation <publishing-session-cancellation>`.
+
+Clients **MUST** be prepared for a session status URL to return ``404 Not Found`` once the session has
+terminated and its retention period has elapsed.  A ``404`` on a previously valid session status URL is not in
+itself an error; clients **SHOULD** treat it as indicating that the session no longer exists.  Note that once a
+terminated session has been purged, a request to :ref:`create a new session <publishing-session-multiple>` for
+the same ``name`` and ``version`` will succeed with a ``201 Created`` rather than returning the ``409
+Conflict`` that a still-live session would have produced.
+
+
 .. _publishing-session-extension:
 
 Publishing Session Extension
@@ -1222,6 +1250,15 @@ The client can query status of the file upload session by issuing a ``GET`` requ
 <file-upload-session-response>`.  The server responds to this request with the same payload as the file upload
 session creation response, except with any changes ``status`` and ``expires-at`` reflected.
 
+A file upload session has no existence independent of the publishing session it belongs to, and its status URL
+is retained accordingly.  While the parent publishing session is in a non-terminal state, the server
+**SHOULD** keep each of its file upload session status URLs valid, reporting the file upload session's current
+``status`` -- including a terminal ``canceled`` -- so that a client can observe the outcome of any file it
+uploaded.  Once the parent publishing session itself terminates, its file upload session URLs are retained no
+longer than the parent's own :ref:`status URL <publishing-session-retention>` and **MAY** return ``404 Not
+Found`` thereafter.  As with cancellation, the data-bearing and mechanism portions of these URLs may become
+unavailable as soon as the underlying file data is purged, independent of the status URL.
+
 .. _file-upload-session-extension:
 
 File Upload Session Extension
@@ -1704,6 +1741,16 @@ these constraints upfront is simpler when the project is known at session creati
 project version.  Allowing multiple projects would fundamentally change this model and
 complicate the definition of what "publish" means for a session.
 
+Even with the single-project restriction, this PEP still improves multi-project releases.  A client releasing
+several projects at once can fully :ref:`stage <staged-preview>` every project -- creating a publishing
+session per project and uploading all of its artifacts -- before a final step runs through and
+:ref:`publishes <publishing-session-completion>` each one.  This gives the whole set a "stage everything, then
+publish" workflow, even though each publish is still per-project and atomic on its own.
+
+The single-project session also lays a foundation that a future "publish multiple projects" operation could
+build on as a separate endpoint, coordinating the publication of several already-staged sessions, without
+changing the per-session model defined here.
+
 
 Why is the version required when creating a publishing session?
 ---------------------------------------------------------------
@@ -1777,6 +1824,17 @@ Change History
     creation is best-effort and that the authoritative check happens atomically at publish time, reported
     synchronously as a ``409 Conflict`` or, for a deferred publish, by moving the session to the ``error``
     state with the reason in ``notices``.
+  * Add a **Session Status Retention** section.  Specify that after a session reaches a terminal
+    (``published`` or ``canceled``) state, the server **SHOULD** keep serving its status URL reporting the
+    terminal status for an index-specific retention period, after which it **MAY** return ``404 Not Found``,
+    and that clients must be prepared for such a ``404``.  Reconcile the cancellation rules accordingly: the
+    data-bearing and action URLs may become unavailable once purged, while the status URL is retained.
+    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.
+  * 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.
 
 * `26-Jun-2026 <https://discuss.python.org/t/pep-694-pypi-upload-api-2-0-round-3/107923>`__