Skip to content

Commit 432727f

Browse files
committed
Begin to address William's feedback.
* Require that `name` conform to the normalization rules, and include a link * Require that `version` conform to the version specs, and include a link * RFC 3399 instead of ISO 8601 as the timestamp spec. The RFC is a simpler format that subsets the ISO standard, and is more appropriate to our use case. * Adjust the gentoken() algorithm to be more resistant to tomfoolery. This may still change. * Require `filename` to conform to either the source or binary distribution file name convention, and include links
1 parent dbc787c commit 432727f

1 file changed

Lines changed: 29 additions & 15 deletions

File tree

peps/pep-0694.rst

Lines changed: 29 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -339,10 +339,15 @@ The request includes the following top-level keys:
339339
``api-version`` the value of which must be the string ``"2.0"``.
340340

341341
``name`` (**required**)
342-
The name of the project that this session is attempting to release a new version of.
342+
The name of the project that this session is attempting to release a new version of. The name
343+
**MUST** conform to the `standard package name format
344+
<https://packaging.python.org/en/latest/specifications/name-normalization/#name-normalization>`__
345+
and the server **MUST** normalize the name.
343346

344347
``version`` (**required**)
345-
The version of the project that this session is attempting to add files to.
348+
The version of the project that this session is attempting to add files to. The version string
349+
**MUST** conform to the `packaging version
350+
<https://packaging.python.org/en/latest/specifications/version-specifiers/>`_ specification.
346351

347352
``nonce`` (**optional**)
348353
An additional client-side string input to the
@@ -414,13 +419,14 @@ the following keys:
414419
If the index does *not* support stage previewing, this key **MUST** be omitted.
415420

416421
``expires-at``
417-
An ISO8601 formatted timestamp string representing when the server will expire this session,
418-
and thus all of its content, including any uploaded files and the URL links related to the
419-
session. The session **SHOULD** remain active until at least this time
420-
unless the client itself has canceled or published the session. Servers **MAY** choose to
421-
extend this expiration time, but should never move it earlier.
422-
Clients can query the :ref:`session status <session-status>`
423-
to get the current expiration time of the session.
422+
An :rfc:`3339` formatted timestamp string; this string **MUST** represent a UTC timestamp using the
423+
"Zulu" (i.e. ``Z``) marker, and use only whole seconds (i.e. no fractional seconds). This
424+
timestamp represents when the server will expire this session, and thus all of its content,
425+
including any uploaded files and the URL links related to the session. The session **SHOULD**
426+
remain active until at least this time unless the client itself has canceled or published the
427+
session. Servers **MAY** choose to extend this expiration time, but should never move it
428+
earlier. Clients can query the :ref:`session status <session-status>` to get the current
429+
expiration time of the session.
424430

425431
``status``
426432
A string that contains one of ``pending``, ``published``, ``error``, or ``canceled``,
@@ -585,8 +591,8 @@ following Python code as an example:
585591
586592
def gentoken(name: bytes, version: bytes, nonce: bytes = b''):
587593
h = sha256()
588-
h.update(name)
589-
h.update(version)
594+
h.update(f'{len(name)}'.encode('ascii') + name)
595+
h.update(f'{len(version)}'.encode('ascii') + version)
590596
h.update(nonce)
591597
return h.hexdigest()
592598
@@ -634,7 +640,14 @@ The request looks like:
634640
Besides the standard ``meta`` key, the request JSON has the following additional keys:
635641

636642
``filename`` (**required**)
637-
The name of the file being uploaded.
643+
The name of the file being uploaded. The filename **MUST** conform to either the `source
644+
distribution file name specification
645+
<https://packaging.python.org/en/latest/specifications/source-distribution-format/#source-distribution-file-name>`_
646+
or the `binary distribution file name convention
647+
<https://packaging.python.org/en/latest/specifications/binary-distribution-format/#file-name-convention>`_.
648+
Indexes **SHOULD** validate these file names at the time of the request, returning a ``400 Bad
649+
Request`` error code, as described in the :ref:`session-errors` section when the file names do
650+
not conform.
638651

639652
``size`` (**required**)
640653
The size in bytes of the file being uploaded.
@@ -722,9 +735,10 @@ the following keys:
722735
indicating the current state of the File Upload Session.
723736

724737
``expires-at``
725-
An ISO8601 formatted timestamp string representing when the server will expire this File Upload Session.
726-
The session **SHOULD** remain active until at least this time
727-
unless the client cancels or completes it. Servers **MAY** choose to
738+
An :rfc:`3339` formatted timestamp string representing when the server will expire this File Upload
739+
Session. This string **MUST** represent a UTC timestamp using the "Zulu" (i.e. ``Z``) marker,
740+
and use only whole seconds (i.e. no fractional seconds). The session **SHOULD** remain active
741+
until at least this time unless the client cancels or completes it. Servers **MAY** choose to
728742
extend this expiration time, but should never move it earlier.
729743

730744
``mechanism``

0 commit comments

Comments
 (0)