Update the file upload session section

Author: warsaw

peps/pep-0694.rst

@@ -1,4 +1,3 @@
-
 PEP: 694
 Title: Upload 2.0 API for Python Package Indexes
 Author: Barry Warsaw <[email protected]>, Donald Stufft <[email protected]>, Ee Durbin <[email protected]>
@@ -702,11 +701,11 @@ the file to be uploaded.  These checks may include, but are not limited to:
 - checking if the contents of the ``metadata``, if provided, are valid.
 
 If the server determines that upload should proceed, it will return a ``202 Accepted`` response, with the
-response body below.  The :ref:`status <publishing-session-status>` of the session will also include the filename in the
-``files`` mapping.  If the server cannot proceed with an upload because the ``mechanism`` supplied by the
-client is not supported it **MUST** return a ``422 Unprocessable Content``.  The server **MAY** allow parallel
-uploads of files, but is not required to. If the server determines the upload cannot proceed, it **MUST**
-return a ``409 Conflict``.
+response body below.  The :ref:`status <publishing-session-status>` of the publishing session will also
+include the filename in the ``files`` mapping.  If the server cannot proceed with an upload because the
+``mechanism`` supplied by the client is not supported it **MUST** return a ``422 Unprocessable Content``.  The
+server **MAY** allow parallel uploads of files, but is not required to. If the server determines the upload
+cannot proceed, it **MUST** return a ``409 Conflict``.
 
 .. _file-upload-session-response:
 
@@ -733,8 +732,8 @@ The successful response includes the following:
       }
     }
 
-A ``Retry-After`` response header **MUST** be present
-to indicate to clients when they should next poll for an updated status.
+A ``Retry-After`` response header **MUST** be present to indicate to clients when they should next poll for an
+updated status.
 
 Besides the ``meta`` key, which has the same format as the request JSON, the success response has
 the following keys:
@@ -765,14 +764,14 @@ the following keys:
 File Upload Session Links
 +++++++++++++++++++++++++
 
-For the ``links`` key in the success JSON, the following sub-keys are valid:
+For the ``links`` key in the response payload, the following sub-keys are valid:
 
 ``file-upload-session``
-    The endpoint where actions for this file-upload-session can be performed.
-    including :ref:`canceling and discarding the file upload session <file-upload-session-cancellation>`,
-    :ref:`querying the current file upload session status <publishing-session-status>`,
-    and :ref:`requesting an extension of the file upload session lifetime <publishing-session-extension>`
-    (*if* the server supports it).
+    The endpoint where actions for this file-upload-session can be performed.  including :ref:`completing a
+    file upload session <file-upload-session-completion>`, :ref:`canceling and discarding the file upload
+    session <file-upload-session-cancellation>`, :ref:`querying the current file upload session status
+    <file-upload-session-status>`, and :ref:`requesting an extension of the file upload session lifetime
+    <file-upload-session-extension>` (*if* the server supports it).
 
 .. _file-upload-session-completion:
 
@@ -794,42 +793,40 @@ The requests looks like:
       "action": "complete",
     }
 
-If the server is able to immediately complete the file upload session, it may do so and return a
-``201 Created`` response and set the status of the file upload session to ``complete``.
-If it is unable to immediately complete the file upload session
-(for instance, if it needs to do validation that may take longer than reasonable in a single HTTP
-request), then it may return a ``202 Accepted`` response
-and set the status of the file upload session to ``processing``.
+If the server is able to immediately complete the file upload session, it may do so and return a ``201
+Created`` response and set the status of the file upload session to ``complete``.  If it is unable to
+immediately complete the file upload session (for instance, if it needs to do validation that may take longer
+than reasonable in a single HTTP request), then it may return a ``202 Accepted`` response and set the status
+of the file upload session to ``processing``.
 
-In either case, the server should include a ``Location`` header pointing back to the File Upload
-Session status URL.
+In either case, the server should include a ``Location`` header pointing back to the :ref:`file upload session
+status <file-upload-session-status>` URL.
 
-Servers **MUST** allow clients to poll the file upload session status URL
-to watch for the status to change.
-If the server responds with a ``202 Accepted``,
-clients may poll the file upload session status URL to watch for the status to change.
-Clients **SHOULD** respect the ``Retry-After`` header value
-of the file upload session status response.
+Servers **MUST** allow clients to poll the file upload session status URL to watch for the status to change.
+If the server responds with a ``202 Accepted``, clients may poll the file upload session status URL to watch
+for the status to change.  Clients **SHOULD** respect the ``Retry-After`` header value of the file upload
+session status response.
 
-If an error occurs, the appropriate ``4xx`` code should be returned, as described in the
-:ref:`session-errors` section.
+**FIXME**: Errors
+
+If an error occurs, the appropriate ``4xx`` code should be returned, as described in the :ref:`session-errors`
+section.
 
 
 .. _file-upload-session-cancellation:
 
 Cancellation and Deletion
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-A client can cancel an in-progress file upload session, or delete a file that has been
-completely uploaded.  In both cases, the client performs this by issuing a ``DELETE`` request to
-the file upload session URL of the file they want to delete.
+A client can cancel an in-progress file upload session, or delete a file that has been completely uploaded.
+In both cases, the client performs this by issuing a ``DELETE`` request to the ``links.file-upload-session``
+URL from the :ref:`file upload session creation response <file-upload-session-response>` of the file they want
+to delete.
 
 A successful deletion request **MUST** respond with a ``204 No Content``.
 
-Once canceled or deleted, a client **MUST NOT** assume that
-the previous file upload session resource
-or associated file upload mechanisms
-can be reused.
+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 a Partially or Fully Uploaded File
@@ -838,13 +835,52 @@ Replacing a Partially or Fully Uploaded File
 To replace a session file, the file upload **MUST** have been previously completed, canceled, or
 deleted.  It is not possible to replace a file if the upload for that file is in-progress.
 
-To replace a session file, clients should
-:ref:`cancel and delete the in-progress upload <file-upload-session-cancellation>` by
-issuing a ``DELETE`` to the upload resource URL for the file they want to replace.
-After this, the new file upload can be initiated by beginning
-the entire :ref:`file upload <file-upload-session>` sequence over again.
-This means providing the metadata request again to retrieve a new upload resource URL.
-Clients **MUST NOT** assume that the previous upload resource URL can be reused after deletion.
+To replace a session file, clients should :ref:`cancel and delete the in-progress upload
+<file-upload-session-cancellation>` first.  After this, the new file upload can be initiated by beginning the
+entire :ref:`file upload <file-upload-session>` sequence over again.  This means providing the metadata
+request again to retrieve a new upload resource URL.  Clients **MUST NOT** assume that the previous upload
+resource URL can be reused after deletion.
+
+.. _file-upload-session-status:
+
+File Upload Session Status
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The client can query status of the file upload session by issuing a ``GET`` request to the
+``links.file-upload-session`` URL from the :ref:`file upload session creation response
+<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.
+
+.. _file-upload-session-extension:
+
+File Upload Session Extension
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Servers **MAY** allow clients to extend file upload sessions, but the overall lifetime and number of
+extensions allowed is left to the server.  To extend a file upload session, a client issues a ``POST`` request
+to the ``links.file-upload-session`` URL from the :ref:`file upload session creation response
+<file-upload-session-response>`.
+
+The request looks like:
+
+.. code-block:: json
+
+    {
+      "meta": {
+        "api-version": "2.0"
+      },
+      "action": "extend",
+      "extend-for": 3600
+    }
+
+The number of seconds specified is just a suggestion to the server for the number of additional seconds to
+extend the current file upload session.  For example, if the client wants to extend session for another hour,
+``extend-for`` would be ``3600``.  Upon successful extension, the server will respond with the same :ref:`file
+upload session creation response body <file-upload-session-response>` that they got when they initially
+created the publishing session, except with any changes to ``status`` or ``expires-at`` reflected.
+
+If the server refuses to extend the session for the requested number of seconds, it **MUST** still return a
+success response, and the ``expires-at`` key will simply reflect the current expiration time of the session.
 
 
 .. _staged-preview: