Skip to content

RESUMABLE: Redefine Upload-Complete on the server side #3404

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
guoye-zhang wants to merge 1 commit into
base: main
Choose a base branch
from
+7 −4
Open

RESUMABLE: Redefine Upload-Complete on the server side #3404

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 7 additions & 4 deletions draft-ietf-httpbis-resumable-upload.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -204,7 +204,7 @@ In some cases, clients might prefer to upload a representation as a series of pa

This example shows how the client, communicating with a resource known to support resumable upload, can upload parts of a representation incrementally.

1) The client is aware that the targetted resource supports resumable uploads and therefore starts the upload with the `Upload-Complete` field value set to false and the first part of the representation.
1) The client is aware that the targeted resource supports resumable uploads and therefore starts the upload with the `Upload-Complete` field value set to false and the first part of the representation.

~~~ aasvg
Client Server
Expand Down Expand Up @@ -317,10 +317,12 @@ The `Upload-Offset` header field in responses serves as an acknowledgement of th

An upload is incomplete until it is explicitly marked as completed by the client. After this point, no representation data can be appended anymore.

The `Upload-Complete` request and response header field conveys the completeness state. `Upload-Complete` is an Item Structured Header Field ({{STRUCTURED-FIELDS}}). Its value is a Boolean ({{Section 3.3.6 of STRUCTURED-FIELDS}}) and indicates whether the upload is complete or not. Other values MUST cause the entire header field to be ignored.
The `Upload-Complete` request header field conveys the completeness state. `Upload-Complete` is an Item Structured Header Field ({{STRUCTURED-FIELDS}}). Its value is a Boolean ({{Section 3.3.6 of STRUCTURED-FIELDS}}) and indicates whether the upload is complete or not. Other values MUST cause the entire header field to be ignored.

An upload is marked as completed if a request for creating the upload resource ({{upload-creation}}) or appending to it ({{upload-appending}}) included the `Upload-Complete` header field with a true value and the request content was fully processed.

The `Upload-Complete` response header field distinguishes the response from the initial targeted resource or the temporary upload resource. The value of true means the response is from the the initial targeted resource, and the value of false means the response is from the temporary upload resource. It is worth noting that `Upload-Complete` can be true even if the upload is not complete if the targeted resource decides to generate an early response.
Copy link
Copy Markdown
Contributor

@GrantGryczan GrantGryczan Mar 29, 2026

Choose a reason for hiding this comment

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

It is worth noting that Upload-Complete can be true even if the upload is not complete

This is confusing, especially since arguably Upload-Complete being true defines the notion that the upload was completed in some sense. How about this (also fixed a typo, "the the"):

Suggested change
The `Upload-Complete` response header field distinguishes the response from the initial targeted resource or the temporary upload resource. The value of true means the response is from the the initial targeted resource, and the value of false means the response is from the temporary upload resource. It is worth noting that `Upload-Complete` can be true even if the upload is not complete if the targeted resource decides to generate an early response.
The `Upload-Complete` response header field distinguishes the response from the initial targeted resource or the temporary upload resource. The value of true means the response is from the initial targeted resource, and the value of false means the response is from the temporary upload resource. It is worth noting that `Upload-Complete` can be true even when the full representation data was not received if the targeted resource decides to generate an early response.


### Length {#upload-length}

The length of an upload is the number of bytes of representation data that the client intends to upload.
Expand Down Expand Up @@ -485,7 +487,7 @@ Location: https://example.com/upload/0587fa44b
HTTP/1.1 500 Internal Server Error
~~~

D) The following example shows an upload creation being rejected by the server because uploads to the targetted resource are not allowed. The client cannot continue the upload.
D) The following example shows an upload creation being rejected by the server because uploads to the targeted resource are not allowed. The client cannot continue the upload.

~~~ http-message
POST /upload-not-allowed HTTP/1.1
Expand Down Expand Up @@ -523,7 +525,7 @@ If the client received a response with a
A successful response to a `HEAD` request against an upload resource

- MUST include the offset in the `Upload-Offset` header field ({{upload-offset}}),
- MUST include the completeness state in the `Upload-Complete` header field ({{upload-complete}}),
- MUST include the `Upload-Complete` header field ({{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 ({{upload-length}}),
- MUST indicate the limits in the `Upload-Limit` header field ({{upload-limit}}), and
- SHOULD include the `Cache-Control` header field with the value `no-store` to prevent HTTP caching ({{CACHING}}).
Expand Down Expand Up @@ -1000,6 +1002,7 @@ Reference:
* Clear up different responsibilities of server and upload resource.
* Relax recommendations on client handling greater offsets.
* Clarify client behavior for 413 responses.
* Redefine Upload-Complete on the server side

## Since draft-ietf-httpbis-resumable-upload-10
{:numbered="false"}
Expand Down
Loading