RESUMABLE: Require offset and length to match upon completion by Acconut · Pull Request #3463 · httpwg/http-extensions

Acconut · 2026-06-23T06:28:42Z

Closes #3430.

This PR clarifies that the offset and length must match when the upload is about to be completed. The draft had already requirements that the length derived from Content-Length is consistent, but there was a loophole when the header is missing:

The only loophole is that this is only specified for requests with Content-Length. This header isn't always present (e.g. when Transfer-Encoding: chunked is used), so this case isn't prohibited at the moment:

Empty POST request with Upload-Length: 1000 and Upload-Complete: ?0

PATCH request with Upload-Complete: ?1, no Content-Length, but 500 bytes of content

(from #3430 (comment))

This gap is closed by explicitly saying that the length must be consistent in the end.

GrantGryczan · 2026-06-23T07:45:30Z

Why do we deactivate the upload resource instead of simply responding with a 4xx error with Upload-Complete: ?0? Couldn't the client recover from this mistake by simply resending the correct final append? This seems particularly problematic if the inconsistent length is merely a transmission error, not some permanent bad client state. Why would such an error result in the entire upload failing?

I'd think we'd want to just make this fall under the existing inconsistent length problem type.

Acconut · 2026-06-23T09:12:50Z

You're right. We can adjust the language to meet the existing requirements on keeping the length consistent.

guoye-zhang · 2026-06-23T16:23:38Z

I think this should be a hard failure. It's unclear how this could be the result of a transmission error, other than TCP somehow corrupting the bytes which is outside the scope of the protocol to recover. However, I'm also fine with it being retryable since it doesn't complicate the implementation.

GrantGryczan · 2026-06-23T20:56:16Z

Even if it isn't a realistic transmission error, the server implementation may be able to be simpler if it can just reuse the inconsistent upload length 4xx response, rather than special-casing this one means that the upload length can be inconsistent.

Apply the terminology and problem type updates from resumable-upload-length. Co-authored-by: Cursor <cursoragent@cursor.com>

Acconut · 2026-06-24T20:53:53Z

I've adjusted the section of length to use representation's length instead of upload length. We introduced this term, but it has the same meaning as the representation's length, so I think this makes it easier for the reader to understand what value is communicated. It should also be clearer that the length must stay consistent over the upload. The Upload-Length header is left untouched since it's now just a way to communicate the representation's length.

Please let me know what you think.

GrantGryczan · 2026-06-24T21:44:36Z

 ### Length {#upload-length}

-The length of an upload is the number of bytes of representation data that the client intends to upload.
+The length of the representation data might not be known when starting the transfer, for example, because the representation is taken from a streaming source. The representation's length will, however, be known at the latest when the upload is complete.


This last sentence is untrue. The server can mark an upload as completed (I assume you meant "completed", not "complete") before the length is known.

I'm not sure I understand. The length will always be known when the upload is complete (i.e. request with Upload-Complete: ?1 was fully received) because the full representation has been received at that point.

The server can send an early response with Upload-Complete: ?1, deeming the upload complete without a request being sent with Upload-Complete: ?1.

In that case the upload is complete and the server learns the length of the transferred representation. No further data can be appended and the length is final.

But the client never finished transferring the representation, and it didn't communicate the length through either of the two length indicators this PR documents, so the server cannot know the full representation's length. Setting aside semantics though, the server implementation required to actually compute the length from a request discarded early seems useless and unnecessarily complex when the server no longer needs to be aware of the length. The server still won't necessarily know the length, and unlike for the 2 indicators, it isn't required to.

Can we just rephrase this as “when the client completes the upload”?

Can we just rephrase this as “when the client completes the upload”?

That's possible. Thinking out load, the consequence would be that if the server serves an early response, the upload either

is completed and does not have a length, or

is completed, but offset < length.

Both seem fine to me since the server stopped the upload early, so it's not unexpected that the upload is halted in such an intermittent state. Using the suggested phrasing would resolve the topic in a rather simple way, wouldn't it?

Yes, it would! (I swore I reacted to Guoye's comment with 👍 before, but it disappeared.)

GrantGryczan · 2026-06-24T22:11:52Z

 - MUST include the offset in the `Upload-Offset` header field ({{upload-offset}}),
 - MUST include the `Upload-Complete` header field ({{upload-complete}}) indicating whether a final response was produced from processing the uploaded representation,
- 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 ({{upload-length}}),
+- MUST include the representation's length in the `Upload-Length` header field if the client has supplied one through corresponding headers as described in ({{upload-length}}),


Why don't we just remove "through corresponding headers" since that could be misinterpreted as excluding the final request content length itself as a signal? I know you're referring to when Upload-Complete: ?1 is present, but I don't think that header itself is what supplies the representation's length. This previously referred to either Upload-Length or Upload-Offset+Content-Length, which actually did supply the length.

Suggested change

- MUST include the representation's length in the `Upload-Length` header field if the client has supplied one through corresponding headers as described in ({{upload-length}}),

- MUST include the representation's length in the `Upload-Length` header field if the client has indicated one as described in ({{upload-length}}),

There original phrasing has been chosen on purpose based on feedback from the previous Working Group Last Call (#3204). So let's keep that and just adjust it to use "representation's length".

Suggested change

- MUST include the representation's length in the `Upload-Length` header field if the client has supplied one through corresponding headers as described in ({{upload-length}}),

- MUST include the representation's length in the `Upload-Length` header field, unless the client has not supplied one, by providing the corresponding headers as described in ({{upload-length}}),

Yeah, but that was before the representation's length was specified as being deduced from things other than headers. I don't think this phrasing is appropriate anymore. The reason that phrasing was chosen is because it clarifies under what circumstances the server must know the length. Citing the aforementioned indicators rather than "headers" should be equally sufficient.

If you disagree, I'd want to hear @LPardue's opinion on this before this is merged. (I don't consider my comment resolved, so if you're able to un-mark it as resolved, that would be nice so I don't have to start a new thread for this review.)

How about this?

MUST include the representation's length in the Upload-Length header field, unless the server has not discovered the length through the mechanisms described in ({{upload-length}}),

This addresses my problem, but to also address the point of the aforementioned PR, shouldn't it mention the client indicating the length rather than the server discovering it?

GrantGryczan · 2026-06-24T22:29:22Z

This may be out of scope, but do we want to rename the Upload-Length header field to Repr-Length if it's really just an indicator for the representation's length? This seems more broadly useful than just for resumable uploads, and if an HTTP header for that were ever added in the future, it would make Upload-Length completely redundant.

Basing this on Content-Digest vs. Repr-Digest, we have Content-Length but no Repr-Length.

Co-authored-by: Grant Gryczan <grantgryczan@gmail.com>

Acconut · 2026-06-25T06:26:25Z

This may be out of scope, but do we want to rename the Upload-Length header field to Repr-Length if it's really just an indicator for the representation's length?

There's value in keeping the header naming consistent (Upload-Complete, Upload-Offset, Upload-Limit, Upload-Length), so the prefix serves a good purpose. In addition, renaming it to Repr-Length would raise more questions about its relation to Content-Length and its general use outside of uploads. I'm not sure there's much to gain here.

guoye-zhang · 2026-06-26T00:43:11Z


 Title:
-: Inconsistent Upload Length Values
+: Inconsistent Representation Length Values


Should we keep the problem type inconsistent-upload-length since the new name sounds like it might be more widely applicable?

We already defined upload length to be the representation’s length to be uploaded. I suspect most people are still confused about resource vs representation vs content.

We can also keep the previous name 👍

guoye-zhang · 2026-06-26T00:45:23Z

 ### Length {#upload-length}

-The length of an upload is the number of bytes of representation data that the client intends to upload.
+The length of the representation data might not be known when starting the transfer, for example, because the representation is taken from a streaming source. The representation's length will, however, be known at the latest when the upload is complete.


Can we just rephrase this as “when the client completes the upload”?

Require offset and length to match upon completion

80e1950

Acconut self-assigned this Jun 23, 2026

Acconut requested review from LPardue and guoye-zhang as code owners June 23, 2026 06:28

Acconut added the resumable-upload label Jun 23, 2026

Acconut mentioned this pull request Jun 23, 2026

RESUMABLE: Unclear how server should handle completing request with insufficient length #3430

Open

guoye-zhang reviewed Jun 23, 2026

View reviewed changes

Comment thread draft-ietf-httpbis-resumable-upload.md Outdated

Marius Kleidl and others added 2 commits June 24, 2026 22:14

Better changelog

7dd88df

Replace uses of term "upload length" with "representation's length"

8543fd7

Apply the terminology and problem type updates from resumable-upload-length. Co-authored-by: Cursor <cursoragent@cursor.com>

Acconut requested a review from guoye-zhang June 24, 2026 20:50

Clarify that length was can change from unknown to known

1b3a042

GrantGryczan suggested changes Jun 24, 2026

View reviewed changes

Acconut and others added 2 commits June 25, 2026 08:15

Apply suggestions from code review

9a58d0d

Co-authored-by: Grant Gryczan <grantgryczan@gmail.com>

Update draft-ietf-httpbis-resumable-upload.md

f68c037

Update draft-ietf-httpbis-resumable-upload.md

d6d629c

guoye-zhang approved these changes Jun 26, 2026

View reviewed changes

	- MUST include the representation's length in the `Upload-Length` header field if the client has supplied one through corresponding headers as described in ({{upload-length}}),
	- MUST include the representation's length in the `Upload-Length` header field if the client has indicated one as described in ({{upload-length}}),

Uh oh!

Conversation

Acconut commented Jun 23, 2026

Uh oh!

Uh oh!

GrantGryczan commented Jun 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Acconut commented Jun 23, 2026

Uh oh!

guoye-zhang commented Jun 23, 2026

Uh oh!

GrantGryczan commented Jun 23, 2026

Uh oh!

Acconut commented Jun 24, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

GrantGryczan Jun 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

GrantGryczan Jun 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

GrantGryczan Jun 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

GrantGryczan Jun 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

GrantGryczan commented Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Acconut commented Jun 25, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

GrantGryczan commented Jun 23, 2026 •

edited

Loading

GrantGryczan Jun 25, 2026 •

edited

Loading

GrantGryczan Jun 26, 2026 •

edited

Loading

GrantGryczan Jun 25, 2026 •

edited

Loading

GrantGryczan Jun 25, 2026 •

edited

Loading

GrantGryczan commented Jun 24, 2026 •

edited

Loading