Fully document the file upload session state machine

Author: warsaw

peps/pep-0694.rst

@@ -935,7 +935,7 @@ the following keys:
 
 ``status``
     A string with valid values ``pending``, ``processing``, ``complete``, ``error``, and ``canceled``
-    indicating the current state of the file upload session.
+    indicating the current :ref:`state of the file upload session <file-upload-session-states>`.
 
 ``expires-at``
     An :rfc:`3339` formatted timestamp string representing when the server will expire this file upload
@@ -969,6 +969,98 @@ For the ``links`` key in the response payload, the following sub-keys are valid:
     <file-upload-session-extension>` (via ``POST``).  If the server does not support file upload session
     extensions, this key **MUST** be omitted.
 
+.. _file-upload-session-states:
+
+File Upload Session States
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A file upload session is always in exactly one of the following states, reported by the ``status`` key of the
+:ref:`file upload session status response <file-upload-session-response>`.  The same value is reflected for the
+file in the ``files`` mapping of the :ref:`publishing session status <publishing-session-files>`.
+
+``pending``
+    The file upload session has been created and the negotiated :ref:`upload mechanism
+    <file-upload-mechanisms>` is being executed; the file's bytes are in transit or not yet fully transferred.
+    A newly created session starts in this state and remains in it until the client :ref:`completes
+    <file-upload-session-completion>` or :ref:`cancels <file-upload-session-cancellation>` the upload.  A file
+    whose upload is still ``pending`` cannot be :ref:`replaced <replacing-files>`.
+
+``processing``
+    The client has requested completion and the server accepted the request for deferred processing, returning
+    a ``202 Accepted`` (see :ref:`file-upload-session-completion`).  This is a transitional state; the client
+    polls the :ref:`file upload session status <file-upload-session-status>`, respecting the ``Retry-After``
+    header, until it resolves to ``complete`` or ``error``.
+
+``complete``
+    The file has been fully uploaded, validated, and accepted into the publishing session.  The file can still
+    be :ref:`deleted <file-upload-session-cancellation>`, which removes it from the publishing session and
+    moves this session to ``canceled``.
+
+``error``
+    The upload failed and the file is **not** in a usable state.  Unlike a :ref:`publishing session in the
+    error state <publishing-session-states>`, a file upload session cannot be repaired in place: the client
+    **MUST** :ref:`cancel or delete <file-upload-session-cancellation>` the file and, if it still wants to
+    upload it, begin an entirely new file upload session.  A file upload session enters ``error`` whenever a
+    completion attempt fails -- whether the server detects the failure synchronously within the ``complete``
+    request, or asynchronously while the session is ``processing``.
+
+``canceled`` (terminal)
+    The session was canceled (an in-progress upload) or its completed file was deleted.  The session resource
+    and its associated upload mechanisms **MUST NOT** be assumed reusable; recovering or replacing the file
+    requires a new file upload session.
+
+Only ``canceled`` is terminal.  Both ``complete`` and ``error`` still permit a ``DELETE`` (which moves the
+session to ``canceled``); from ``error``, deletion is the only forward action.
+
+The transitions between these states are:
+
+.. list-table::
+   :header-rows: 1
+
+   * - From
+     - Event
+     - To
+   * - *(none)*
+     - File upload session created (``202 Accepted``)
+     - ``pending``
+   * - ``pending``
+     - Upload mechanism executes (bytes transferred)
+     - ``pending``
+   * - ``pending``
+     - Completion request completed immediately (``201 Created``)
+     - ``complete``
+   * - ``pending``
+     - Completion request accepted for deferred processing (``202 Accepted``)
+     - ``processing``
+   * - ``pending``
+     - Completion request fails synchronously
+     - ``error``
+   * - ``pending``
+     - Cancellation requested (``DELETE``)
+     - ``canceled``
+   * - ``processing``
+     - Deferred processing succeeds
+     - ``complete``
+   * - ``processing``
+     - Deferred processing fails
+     - ``error``
+   * - ``processing``
+     - Cancellation requested
+     - rejected with ``409 Conflict`` (see :ref:`file-upload-session-cancellation`)
+   * - ``complete``
+     - File deleted (``DELETE``)
+     - ``canceled``
+   * - ``error``
+     - File deleted (``DELETE``)
+     - ``canceled``
+
+Unlike a publishing session -- where a synchronous publish failure leaves the session editable and only a
+*deferred* failure reaches the ``error`` state -- a file upload session treats *any* completion failure as
+fatal to the file, because a partially or incorrectly uploaded file cannot be edited in place.  Both a
+synchronous and a deferred completion failure therefore move the session to ``error``, from which the client
+deletes the file and starts over.
+
+
 .. _file-upload-session-completion:
 
 Complete a File Upload Session
@@ -1002,6 +1094,11 @@ If the server responds with a ``202 Accepted``, clients may poll the file upload
 for the status to change.  Clients **SHOULD** respect the ``Retry-After`` header value of the file upload
 session status response.
 
+If a completion attempt fails -- synchronously (in which case the server also returns an :ref:`error response
+<session-errors>`) or asynchronously while the session is ``processing`` -- the session moves to the
+:ref:`error state <file-upload-session-states>`, from which the client must :ref:`cancel or delete
+<file-upload-session-cancellation>` the file and start a new file upload session to retry.
+
 
 .. _file-upload-session-cancellation:
 
@@ -1015,10 +1112,18 @@ to delete.
 
 A successful deletion request **MUST** respond with a ``204 No Content``.
 
+A ``DELETE`` is permitted while the session is ``pending`` (canceling an in-progress upload), ``complete``
+(deleting an uploaded file), or ``error`` (discarding a failed upload).  If the session is in the
+``processing`` state -- that is, a deferred completion is already underway -- the server **MUST** reject the
+``DELETE`` with a ``409 Conflict``, since the outcome is already being decided.  The client can instead wait
+for processing to resolve and then delete the file if needed.
+
 Once canceled or deleted, a client **MUST NOT** assume that the previous file upload session resource or
 associated file upload mechanisms can be reused.
 
 
+.. _replacing-files:
+
 Replacing a Partially or Fully Uploaded File
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1612,6 +1717,11 @@ Change History
     entering ``error``, and require the server to reject cancellation with a ``409 Conflict`` while a session is
     ``processing``.  Key the **Multiple Session Creation Requests** rule off any non-terminal state rather than
     ``pending``.
+  * Document the file upload session state machine with a **File Upload Session States** section and transition
+    table.  Specify that any completion failure -- synchronous or deferred -- moves the session to ``error``,
+    that an ``error`` file cannot be repaired in place (the client cancels or deletes it and starts a new file
+    upload session), and that the server **MUST** reject a ``DELETE`` with a ``409 Conflict`` while a session
+    is ``processing``.
 
 * `07-Dec-2025 <https://discuss.python.org/t/pep-694-pypi-upload-api-2-0-round-2/101483/35>`__