RESUMABLE: Clarify offset handling#3479
Open
Acconut wants to merge 1 commit into
Open
Conversation
guoye-zhang
reviewed
Jul 6, 2026
|
|
||
| - The offset can be explicitly retrieved from the upload resource ({{offset-retrieving}}). | ||
| - Interim and final responses when creating the upload ({{upload-creation}}) or appending ({{upload-appending}}) can include the `Upload-Offset` header field. | ||
| - Final responses for appending representation data ({{upload-appending}}) with a `2XX` status code or the `Upload-Complete: ?1` acknowledge that the entire request content was received and the offset increased by the length of the appended representation data. |
Contributor
There was a problem hiding this comment.
I think the offset is only relevant for 2xx with Upload-Complete: ?0. If Upload-Complete: ?1, the offset is no longer relevant since the client won't be resuming.
GrantGryczan
suggested changes
Jul 6, 2026
GrantGryczan
left a comment
GrantGryczan
left a comment
Contributor
There was a problem hiding this comment.
Excellent! I love the direction of this PR.
| A client can continue the upload and append representation data by sending a `PATCH` request with the `application/partial-upload` media type ({{media-type-partial-upload}}) to the upload resource. The request content is the representation data to append. The request can benefit from incremental delivery; see {{incremental}}. | ||
|
|
||
| The client MUST indicate the offset of the request content inside the representation data by including the `Upload-Offset` header field. To ensure that the upload resource will accept the request, the offset SHOULD be taken from an immediate previous response for retrieving the offset ({{offset-retrieving}}) or appending representation data ({{upload-appending}}). | ||
| The client MUST indicate the offset of the request content inside the representation data by including the `Upload-Offset` header field. To ensure that the upload resource will accept the request, the offset SHOULD be taken from an immediate previous response for retrieving the offset ({{offset-retrieving}}), creating the upload ({{upload-creation}}), or appending representation data ({{upload-appending}}). |
Contributor
There was a problem hiding this comment.
What about taking it implicitly from 2xx responses? Also, is there a particular reason this is a "SHOULD" and not a "MUST"? No well-behaved client will ever do anything different, as far as I can think of.
Comment on lines
697
to
+701
| Resumable uploads, as defined in this document, do not permit uploading representation data in parallel to the same upload resource. The client MUST NOT perform multiple representation data transfers for the same upload resource in parallel. | ||
|
|
||
| Even if the client is well-behaved and doesn't send concurrent requests, network interruptions can occur in such a way that the client considers a request as failed while the server is unaware of the problem and considers the request still ongoing. The client might then try to resume the upload with the best intentions, resulting in concurrent requests from the server's perspective. Therefore, the server MUST take measures to prevent race conditions, data loss and corruption from concurrent requests to append representation data ({{upload-appending}}) and/or cancellation ({{upload-cancellation}}) to the same upload resource. In addition, the server MUST NOT send outdated information in responses when retrieving the offset ({{offset-retrieving}}). This means that the offset sent by the server MUST be accepted in a subsequent request to append representation data if no other request to append representation data or cancel was received in the meantime. In other words, clients have to be able to use received offsets. | ||
| Even if the client is well-behaved and doesn't send concurrent requests, network interruptions can occur in such a way that the client considers a request as failed while the server is unaware of the problem and considers the request still ongoing. The client might then try to resume the upload with the best intentions, resulting in concurrent requests from the server's perspective. Therefore, the server MUST take measures to prevent race conditions, data loss and corruption from concurrent requests to append representation data ({{upload-appending}}) and/or cancellation ({{upload-cancellation}}) to the same upload resource. In addition, the server MUST NOT send outdated information in responses. This means that the offset communicated through responses as defined in {{upload-offset}} MUST be accepted in a subsequent request to append representation data if no other request to append representation data or cancel was received in the meantime. In other words, clients have to be able to use received offsets. |
Contributor
There was a problem hiding this comment.
This "MUST be accepted" requirement should exclude offsets from interim responses. I advise changing "if no other request to append representation data or cancel was received in the meantime" to be more general, including ongoing requests as well as upload creation requests.
GrantGryczan
suggested changes
Jul 6, 2026
|
|
||
| If the client wants to resume the upload after an interruption, it has to know the amount of representation data processed by the upload resource so far. It can fetch the offset by sending a `HEAD` or `GET` request to the upload resource. Using `HEAD` is RECOMMENDED, since response content is not required for resumption. Upon a successful response, the client can continue the upload by appending representation data ({{upload-appending}}) starting at the offset indicated by the `Upload-Offset` response header field. | ||
|
|
||
| The offset can be less than or equal to the number of bytes of representation data that the client has already sent. The client is expected to handle backtracking of a reasonable length. On the other hand, the offset can be greater than the amount of sent representation data if the upload resource obtained additional representation data on behalf of the client. If the client is not able to provide the representation data at the given offset, the upload MUST be considered a failure. The client then MUST NOT continue the upload and SHOULD cancel the upload ({{upload-cancellation}}). |
Contributor
There was a problem hiding this comment.
Oh, also, while we're clarifying client offset behavior, I'd like to suggest the non-controversial editorial change I previously mentioned relating to #3451's 4th point as well, which would make me more comfortable closing the issue. The offset can be greater for any reason, so this should only be framed as an example. And resources don't obtain things; servers do.
Suggested change
| The offset can be less than or equal to the number of bytes of representation data that the client has already sent. The client is expected to handle backtracking of a reasonable length. On the other hand, the offset can be greater than the amount of sent representation data, for example, if the server obtained additional representation data on behalf of the client. If the client is not able to provide the representation data at the given offset, the upload MUST be considered a failure. The client then MUST NOT continue the upload and SHOULD cancel the upload ({{upload-cancellation}}). |
EDIT: Not sure why GitHub is rendering this suggestion as replacing an empty line. Line 535 is not empty. I'm going to guess it just hit a character limit.
GrantGryczan
reviewed
Jul 6, 2026
|
|
||
| - The offset can be explicitly retrieved from the upload resource ({{offset-retrieving}}). | ||
| - Interim and final responses when creating the upload ({{upload-creation}}) or appending ({{upload-appending}}) can include the `Upload-Offset` header field. | ||
| - Final responses for appending representation data ({{upload-appending}}) with a `2XX` status code or the `Upload-Complete: ?1` acknowledge that the entire request content was received and the offset increased by the length of the appended representation data. |
Contributor
There was a problem hiding this comment.
Are you sure we don't want to comment on the possibility of these sources of information simultaneously contradicting each other (which was the 2nd point in #3451)? I won't argue if not, but I just want to double-check, because it really stands out as odd to me that this real possibility isn't clarified, especially with this new framing.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR addresses two comments:
From #3451:
To address this, mention that a client can learn the offset implicitly through responses.
From #3222:
The text has been expanded to that the client must never observe a decreasing offset value, regardless through which means.
Closes #3451.
Closes #3222.