Skip to content

Conversation

LPardue
Copy link
Contributor

@LPardue LPardue commented Aug 22, 2025

We have the requirement "if the client knows the representation data's length,
it SHOULD include the Upload-Length". Which means the server can be a position
to either know, or not know the value.

This change makes a minor tweak to the text to highlight that when the server
was given a length it really MUST respond with it but when it didn't get given
one it can't.

Fixes #3187

- MUST include the offset in the `Upload-Offset` header field ({{upload-offset}}),
- MUST include the completeless state in the `Upload-Complete` header field ({{upload-complete}}),
- MUST include the length in the `Upload-Length` header field if known ({{upload-length}}),
- MUST include the length in the `Upload-Length` header field unless the client has not supplied one ({{upload-length}}),
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The client can also specify the complete upload length implicitly through the combination of Content-Length and Upload-Complete: ?1. Wondering if the phrasing should be "unless the total length is unknown".

Copy link
Contributor Author

@LPardue LPardue Aug 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

or "unless the client has not supplied one (either by supplying its own upload-length or providing an Upload-Complete:?1 with a Content-Length)"

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, that works

- MUST include the offset in the `Upload-Offset` header field ({{upload-offset}}),
- MUST include the completeless state in the `Upload-Complete` header field ({{upload-complete}}),
- MUST include the length in the `Upload-Length` header field if known ({{upload-length}}),
- MUST include the length in the `Upload-Length` header field unless the client has not supplied one, either by providing its own `Upload-Length` ({{upload-length}}) or providing an Upload-Complete:?1 with a Content-Length ({{upload-complete}}),
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The text could also just reference Section 4.1.3, which explains how the length of an upload can be discovered:

There are two different ways for the client to indicate and the upload resource to discover the length from requests for creating the upload resource (Section 4.2) or appending to it (Section 4.4):

  • If the request includes the Upload-Complete field value set to true and a valid Content-Length header field, the request content is the remaining representation data. The length is then the sum of the current offset (Section 4.1.1) and the Content-Length header field value.
  • The request can include the Upload-Length request and response header field. Upload-Length is an Item Structured Header Field ([STRUCTURED-FIELDS]). Its value is a non-negative Integer (Section 3.3.1 of [STRUCTURED-FIELDS]) and indicates the number of bytes of the entire representation data. Other values MUST cause the entire header field to be ignored.

(from https://httpwg.org/http-extensions/draft-ietf-httpbis-resumable-upload.html#section-4.1.3-2)

Maybe something along these lines:

Suggested change
- MUST include the length in the `Upload-Length` header field unless the client has not supplied one, either by providing its own `Upload-Length` ({{upload-length}}) or providing an Upload-Complete:?1 with a Content-Length ({{upload-complete}}),
- MUST include the length in the `Upload-Length` header field unless the client has not supplied one, by providing the corresponding headers as described in Section 4.1.3,

That might be a bit more watertight.

Copy link
Contributor Author

@LPardue LPardue Sep 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm happy to avoid restating requirements in multiple places in the document but I'd probably want to land #3200 first

@LPardue
Copy link
Contributor Author

LPardue commented Oct 20, 2025

I plan to rebase this and act on @Acconut's suggestion later today

@LPardue LPardue merged commit 00b2cd5 into main Oct 20, 2025
2 checks passed
@LPardue LPardue deleted the lucas/fix-3187 branch October 20, 2025 20:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Development

Successfully merging this pull request may close these issues.

RESUMABLE: "MUST if" is a poor normative construction

4 participants