draft-ietf-httpbis-resumable-upload-11.txt   draft-ietf-httpbis-resumable-upload-latest.txt 
HTTP Working Group M. Kleidl, Ed. HTTP Working Group M. Kleidl, Ed.
Internet-Draft Transloadit Internet-Draft Transloadit
Intended status: Standards Track G. Zhang, Ed. Intended status: Standards Track G. Zhang, Ed.
Expires: September 3, 2026 Apple Inc. Expires: September 8, 2026 Apple Inc.
L. Pardue, Ed. L. Pardue, Ed.
Cloudflare Cloudflare
March 02, 2026 March 07, 2026
Resumable Uploads for HTTP Resumable Uploads for HTTP
draft-ietf-httpbis-resumable-upload-11 draft-ietf-httpbis-resumable-upload-latest
Abstract Abstract
HTTP data transfers can encounter interruption due to reasons such as HTTP data transfers can encounter interruption due to reasons such as
canceled requests or dropped connections. If the intended recipient canceled requests or dropped connections. If the intended recipient
can indicate how much of the data was received prior to interruption, can indicate how much of the data was processed prior to
a sender can resume data transfer at that point instead of attempting interruption, a sender can resume data transfer at that point instead
to transfer all of the data again. HTTP range requests support this of attempting to transfer all of the data again. HTTP range requests
concept of resumable downloads from server to client. This document support this concept of resumable downloads from server to client.
describes a mechanism that supports resumable uploads from client to This document describes a mechanism that supports resumable uploads
server using HTTP. from client to server using HTTP.
About This Document About This Document
This note is to be removed before publishing as an RFC. This note is to be removed before publishing as an RFC.
Status information for this document may be found at Status information for this document may be found at
<https://datatracker.ietf.org/doc/draft-ietf-httpbis-resumable- <https://datatracker.ietf.org/doc/draft-ietf-httpbis-resumable-
upload/>. upload/>.
Discussion of this document takes place on the HTTP Working Group Discussion of this document takes place on the HTTP Working Group
skipping to change at page 2, line 10 skipping to change at page 2, line 10
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on September 3, 2026. This Internet-Draft will expire on September 8, 2026.
Copyright Notice Copyright Notice
Copyright (c) 2026 IETF Trust and the persons identified as the Copyright (c) 2026 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 43 skipping to change at page 2, line 43
known size . . . . . . . . . . . . . . . . . . . . . . . 6 known size . . . . . . . . . . . . . . . . . . . . . . . 6
3.2. Example 2: Upload as a series of parts . . . . . . . . . 8 3.2. Example 2: Upload as a series of parts . . . . . . . . . 8
4. Upload Resource . . . . . . . . . . . . . . . . . . . . . . . 10 4. Upload Resource . . . . . . . . . . . . . . . . . . . . . . . 10
4.1. State . . . . . . . . . . . . . . . . . . . . . . . . . . 11 4.1. State . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.1.1. Offset . . . . . . . . . . . . . . . . . . . . . . . 11 4.1.1. Offset . . . . . . . . . . . . . . . . . . . . . . . 11
4.1.2. Completeness . . . . . . . . . . . . . . . . . . . . 11 4.1.2. Completeness . . . . . . . . . . . . . . . . . . . . 11
4.1.3. Length . . . . . . . . . . . . . . . . . . . . . . . 12 4.1.3. Length . . . . . . . . . . . . . . . . . . . . . . . 12
4.1.4. Limits . . . . . . . . . . . . . . . . . . . . . . . 13 4.1.4. Limits . . . . . . . . . . . . . . . . . . . . . . . 13
4.2. Upload Creation . . . . . . . . . . . . . . . . . . . . . 15 4.2. Upload Creation . . . . . . . . . . . . . . . . . . . . . 15
4.2.1. Client Behavior . . . . . . . . . . . . . . . . . . . 15 4.2.1. Client Behavior . . . . . . . . . . . . . . . . . . . 15
4.2.2. Server Behavior . . . . . . . . . . . . . . . . . . . 16 4.2.2. Server Behavior . . . . . . . . . . . . . . . . . . . 17
4.2.3. Examples . . . . . . . . . . . . . . . . . . . . . . 18 4.2.3. Examples . . . . . . . . . . . . . . . . . . . . . . 18
4.3. Offset Retrieval . . . . . . . . . . . . . . . . . . . . 19 4.3. Offset Retrieval . . . . . . . . . . . . . . . . . . . . 20
4.3.1. Client Behavior . . . . . . . . . . . . . . . . . . . 19 4.3.1. Client Behavior . . . . . . . . . . . . . . . . . . . 20
4.3.2. Server Behavior . . . . . . . . . . . . . . . . . . . 20 4.3.2. Server Behavior . . . . . . . . . . . . . . . . . . . 21
4.3.3. Examples . . . . . . . . . . . . . . . . . . . . . . 21 4.3.3. Examples . . . . . . . . . . . . . . . . . . . . . . 21
4.4. Upload Append . . . . . . . . . . . . . . . . . . . . . . 21 4.4. Upload Append . . . . . . . . . . . . . . . . . . . . . . 22
4.4.1. Client Behavior . . . . . . . . . . . . . . . . . . . 22 4.4.1. Client Behavior . . . . . . . . . . . . . . . . . . . 22
4.4.2. Server Behavior . . . . . . . . . . . . . . . . . . . 23 4.4.2. Server Behavior . . . . . . . . . . . . . . . . . . . 23
4.4.3. Examples . . . . . . . . . . . . . . . . . . . . . . 24 4.4.3. Examples . . . . . . . . . . . . . . . . . . . . . . 25
4.5. Upload Cancellation . . . . . . . . . . . . . . . . . . . 25 4.5. Upload Cancellation . . . . . . . . . . . . . . . . . . . 26
4.5.1. Client Behavior . . . . . . . . . . . . . . . . . . . 26 4.5.1. Client Behavior . . . . . . . . . . . . . . . . . . . 26
4.5.2. Server Behavior . . . . . . . . . . . . . . . . . . . 26 4.5.2. Server Behavior . . . . . . . . . . . . . . . . . . . 26
4.5.3. Example . . . . . . . . . . . . . . . . . . . . . . . 26 4.5.3. Example . . . . . . . . . . . . . . . . . . . . . . . 26
4.6. Concurrency . . . . . . . . . . . . . . . . . . . . . . . 26 4.6. Concurrency . . . . . . . . . . . . . . . . . . . . . . . 26
5. Status Code 104 (Upload Resumption Supported) . . . . . . . . 27 5. Status Code 104 (Upload Resumption Supported) . . . . . . . . 28
6. Media Type application/partial-upload . . . . . . . . . . . . 28 6. Media Type application/partial-upload . . . . . . . . . . . . 28
7. Problem Types . . . . . . . . . . . . . . . . . . . . . . . . 28 7. Problem Types . . . . . . . . . . . . . . . . . . . . . . . . 28
7.1. Mismatching Offset . . . . . . . . . . . . . . . . . . . 28 7.1. Mismatching Offset . . . . . . . . . . . . . . . . . . . 28
7.2. Completed Upload . . . . . . . . . . . . . . . . . . . . 29 7.2. Completed Upload . . . . . . . . . . . . . . . . . . . . 29
7.3. Inconsistent Length . . . . . . . . . . . . . . . . . . . 29 7.3. Inconsistent Length . . . . . . . . . . . . . . . . . . . 30
8. Content Codings . . . . . . . . . . . . . . . . . . . . . . . 30 8. Content Codings . . . . . . . . . . . . . . . . . . . . . . . 30
9. Transfer Codings . . . . . . . . . . . . . . . . . . . . . . 30 9. Transfer Codings . . . . . . . . . . . . . . . . . . . . . . 30
10. Integrity Digests . . . . . . . . . . . . . . . . . . . . . . 30 10. Integrity Digests . . . . . . . . . . . . . . . . . . . . . . 31
10.1. Representation Digests . . . . . . . . . . . . . . . . . 30 10.1. Representation Digests . . . . . . . . . . . . . . . . . 31
10.2. Content Digests . . . . . . . . . . . . . . . . . . . . 31 10.2. Content Digests . . . . . . . . . . . . . . . . . . . . 31
11. Responses to Uploads . . . . . . . . . . . . . . . . . . . . 31 11. Responses to Uploads . . . . . . . . . . . . . . . . . . . . 32
12. Upload Strategies . . . . . . . . . . . . . . . . . . . . . . 32 12. Upload Strategies . . . . . . . . . . . . . . . . . . . . . . 32
12.1. Optimistic Upload Creation . . . . . . . . . . . . . . . 32 12.1. Optimistic Upload Creation . . . . . . . . . . . . . . . 33
12.1.1. Upgrading To Resumable Uploads . . . . . . . . . . . 33 12.1.1. Upgrading To Resumable Uploads . . . . . . . . . . . 33
12.2. Careful Upload Creation . . . . . . . . . . . . . . . . 34 12.2. Careful Upload Creation . . . . . . . . . . . . . . . . 34
13. Security Considerations . . . . . . . . . . . . . . . . . . . 34 13. Security Considerations . . . . . . . . . . . . . . . . . . . 34
14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 35 14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36
14.1. HTTP Fields . . . . . . . . . . . . . . . . . . . . . . 35 14.1. HTTP Fields . . . . . . . . . . . . . . . . . . . . . . 36
14.2. HTTP Status Code . . . . . . . . . . . . . . . . . . . . 36 14.2. HTTP Status Code . . . . . . . . . . . . . . . . . . . . 36
14.3. Media Type . . . . . . . . . . . . . . . . . . . . . . . 36 14.3. Media Type . . . . . . . . . . . . . . . . . . . . . . . 36
14.4. HTTP Problem Types . . . . . . . . . . . . . . . . . . . 37 14.4. HTTP Problem Types . . . . . . . . . . . . . . . . . . . 38
15. References . . . . . . . . . . . . . . . . . . . . . . . . . 38 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 38
15.1. Normative References . . . . . . . . . . . . . . . . . . 38 15.1. Normative References . . . . . . . . . . . . . . . . . . 38
15.2. Informative References . . . . . . . . . . . . . . . . . 39 15.2. Informative References . . . . . . . . . . . . . . . . . 39
Appendix A. Changes . . . . . . . . . . . . . . . . . . . . . . 39 Appendix A. Changes . . . . . . . . . . . . . . . . . . . . . . 40
A.1. Since draft-ietf-httpbis-resumable-upload-10 . . . . . . 39 A.1. Since draft-ietf-httpbis-resumable-upload-11 . . . . . . 40
A.2. Since draft-ietf-httpbis-resumable-upload-09 . . . . . . 40 A.2. Since draft-ietf-httpbis-resumable-upload-10 . . . . . . 40
A.3. Since draft-ietf-httpbis-resumable-upload-08 . . . . . . 40 A.3. Since draft-ietf-httpbis-resumable-upload-09 . . . . . . 40
A.4. Since draft-ietf-httpbis-resumable-upload-07 . . . . . . 40 A.4. Since draft-ietf-httpbis-resumable-upload-08 . . . . . . 40
A.5. Since draft-ietf-httpbis-resumable-upload-06 . . . . . . 41 A.5. Since draft-ietf-httpbis-resumable-upload-07 . . . . . . 41
A.6. Since draft-ietf-httpbis-resumable-upload-05 . . . . . . 41 A.6. Since draft-ietf-httpbis-resumable-upload-06 . . . . . . 41
A.7. Since draft-ietf-httpbis-resumable-upload-04 . . . . . . 41 A.7. Since draft-ietf-httpbis-resumable-upload-05 . . . . . . 41
A.8. Since draft-ietf-httpbis-resumable-upload-03 . . . . . . 41 A.8. Since draft-ietf-httpbis-resumable-upload-04 . . . . . . 41
A.9. Since draft-ietf-httpbis-resumable-upload-02 . . . . . . 42 A.9. Since draft-ietf-httpbis-resumable-upload-03 . . . . . . 42
A.10. Since draft-ietf-httpbis-resumable-upload-01 . . . . . . 42 A.10. Since draft-ietf-httpbis-resumable-upload-02 . . . . . . 42
A.11. Since draft-ietf-httpbis-resumable-upload-00 . . . . . . 42 A.11. Since draft-ietf-httpbis-resumable-upload-01 . . . . . . 42
A.12. Since draft-tus-httpbis-resumable-uploads-protocol-02 . . 42 A.12. Since draft-ietf-httpbis-resumable-upload-00 . . . . . . 43
A.13. Since draft-tus-httpbis-resumable-uploads-protocol-01 . . 43 A.13. Since draft-tus-httpbis-resumable-uploads-protocol-02 . . 43
A.14. Since draft-tus-httpbis-resumable-uploads-protocol-00 . . 43 A.14. Since draft-tus-httpbis-resumable-uploads-protocol-01 . . 43
A.15. Since draft-tus-httpbis-resumable-uploads-protocol-00 . . 43
Appendix B. Draft Version Identification . . . . . . . . . . . . 43 Appendix B. Draft Version Identification . . . . . . . . . . . . 43
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 44 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 44
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 44 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 44
1. Introduction 1. Introduction
HTTP data transfers can encounter interruption due to reasons such as HTTP data transfers can encounter interruption due to reasons such as
canceled requests or dropped connections. If the intended recipient canceled requests or dropped connections. If the intended recipient
can indicate how much of the data was received prior to interruption, can indicate how much of the data was processed prior to
a sender can resume data transfer at that point instead of attempting interruption, a sender can resume data transfer at that point instead
to transfer all of the data again. HTTP range requests (see of attempting to transfer all of the data again. HTTP range requests
Section 14 of [HTTP]) support this concept of resumable data (see Section 14 of [HTTP]) support this concept of resumable data
transfers for downloads from server to client. While partial PUT is transfers for downloads from server to client. While partial PUT is
one method for uploading a partial representation (via Content-Range one method for uploading a partial representation (via Content-Range
in the request), there are caveats that affect its deployability; see in the request), there are caveats that affect its deployability; see
Section 14.5 of [HTTP]. Section 14.5 of [HTTP].
Canceled upload request can be triggered for various reasons, Canceled upload request can be triggered for various reasons,
including but not limited to: including but not limited to:
explicit client cancellation: e.g., terminating a user-agent process explicit client cancellation: e.g., terminating a user-agent process
skipping to change at page 4, line 51 skipping to change at page 5, line 4
Utilizing resumable uploads, applications can recover from unintended Utilizing resumable uploads, applications can recover from unintended
interruptions, but also interrupt an upload on purpose to later interruptions, but also interrupt an upload on purpose to later
resume it, for example, when a user wants to pause an upload, the resume it, for example, when a user wants to pause an upload, the
device's network connectivity changes, or bandwidth should be saved device's network connectivity changes, or bandwidth should be saved
for higher priority tasks. for higher priority tasks.
The document introduces the concept of an upload resource to The document introduces the concept of an upload resource to
facilitate resumable uploads (Section 4) and defines new header facilitate resumable uploads (Section 4) and defines new header
fields to communicate the state of the upload (Section 4.1), the fields to communicate the state of the upload (Section 4.1), the
status code "104 (Upload Resumption Supported)" to indicate the status code "104 (Upload Resumption Supported)" to indicate the
server's support for resumable uploads (Section 5), and the resource's support for resumable uploads (Section 5), and the
"application/partial-upload" media type to label partial "application/partial-upload" media type to label partial
representation data when resuming an upload (Section 6). representation data when resuming an upload (Section 6).
2. Conventions and Definitions 2. Conventions and Definitions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in "OPTIONAL" in this document are to be interpreted as described in
BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
skipping to change at page 6, line 16 skipping to change at page 6, line 16
In this example, the client first attempts to upload representation In this example, the client first attempts to upload representation
data with a known size in a single HTTP request to the resource at data with a known size in a single HTTP request to the resource at
"/project/123/files". An interruption occurs and the client then "/project/123/files". An interruption occurs and the client then
attempts to resume the upload using subsequent HTTP requests to the attempts to resume the upload using subsequent HTTP requests to the
upload resource at "/uploads/abc". upload resource at "/uploads/abc".
1) The client notifies the server that it wants to begin an upload 1) The client notifies the server that it wants to begin an upload
(Section 4.2). The server reserves the required resources to accept (Section 4.2). The server reserves the required resources to accept
the upload from the client and then sends an interim response to the the upload from the client and then sends an interim response to the
client, which signals the server's support of resumable upload as client, signaling support for resumable uploads and the upload
well as the upload resource's URI via the Location header field resource's URI via the Location header field (Section 10.2.2 of
(Section 10.2.2 of [HTTP]). The client can start sending the [HTTP]). The client can start sending the representation data in the
representation data in the request content immediately after the request content immediately after the request header. Alternatively,
request header. Alternatively, it could also await the it could also await the acknowledgement in form of the interim
acknowledgement in form of the interim response. response.
Client Server Client Server
| | | |
| POST /project/123/files | | POST /project/123/files |
| Upload-Complete: ?1 | | Upload-Complete: ?1 |
| | | |
| [representation] | | [representation] |
|------------------------------------------->| |------------------------------------------->|
| | | |
| | Reserve resources | | Reserve resources
skipping to change at page 6, line 48 skipping to change at page 6, line 48
| Location: /uploads/abc | | Location: /uploads/abc |
|<-------------------------------------------| |<-------------------------------------------|
| | | |
X--------------Flow Interrupted--------------X X--------------Flow Interrupted--------------X
Figure 1: Upload Creation Figure 1: Upload Creation
2) If the connection to the server is interrupted, the client might 2) If the connection to the server is interrupted, the client might
want to resume the upload. However, before this is possible the want to resume the upload. However, before this is possible the
client needs to know the amount of representation data that the client needs to know the amount of representation data that the
server received before the interruption. It does so by retrieving server processed before the interruption. It does so by retrieving
the offset (Section 4.3) from the upload resource. the offset (Section 4.3) from the upload resource.
Client Server Client Server
| | | |
| HEAD /uploads/abc | | HEAD /uploads/abc |
|------------------------------------------------>| |------------------------------------------------>|
| | | |
| 204 No Content | | 204 No Content |
| Upload-Offset: X | | Upload-Offset: X |
|<------------------------------------------------| |<------------------------------------------------|
skipping to change at page 7, line 45 skipping to change at page 7, line 45
| [representation from offset X] | | [representation from offset X] |
|------------------------------------------------>| |------------------------------------------------>|
| | | |
| 200 OK | | 200 OK |
|<------------------------------------------------| |<------------------------------------------------|
| | | |
Figure 3: Upload Append Figure 3: Upload Append
4) If the client is not interested in completing the upload, it can 4) If the client is not interested in completing the upload, it can
instruct the upload resource to delete the upload and free all instruct the server to delete the upload resource and all associated
related resources (Section 4.5). representation data (Section 4.5).
Client Server Client Server
| | | |
| DELETE /uploads/abc | | DELETE /uploads/abc |
|------------------------------------------------>| |------------------------------------------------>|
| | | |
| 204 No Content | | 204 No Content |
|<------------------------------------------------| |<------------------------------------------------|
| | | |
skipping to change at page 8, line 25 skipping to change at page 8, line 25
3.2. Example 2: Upload as a series of parts 3.2. Example 2: Upload as a series of parts
In some cases, clients might prefer to upload a representation as a In some cases, clients might prefer to upload a representation as a
series of parts sent serially across multiple HTTP messages. One use series of parts sent serially across multiple HTTP messages. One use
case is to overcome server limits on HTTP message content size. case is to overcome server limits on HTTP message content size.
Another use case is where the client does not know the final size of Another use case is where the client does not know the final size of
the representation data, such as when the data originates from a the representation data, such as when the data originates from a
streaming source. streaming source.
This example shows how the client, communicating to a server known to This example shows how the client, communicating with a resource
support resumable upload, can upload parts of a representation known to support resumable upload, can upload parts of a
incrementally. representation incrementally.
1) If the client is aware that the server supports resumable upload, 1) The client is aware that the targetted resource supports resumable
it can start an upload with the "Upload-Complete" field value set to uploads and therefore starts the upload with the "Upload-Complete"
false and the first part of the representation. field value set to false and the first part of the representation.
Client Server Client Server
| | | |
| POST /project/123/files | | POST /project/123/files |
| Upload-Complete: ?0 | | Upload-Complete: ?0 |
| | | |
| [partial representation] | | [partial representation] |
|------------------------------------------------>| |------------------------------------------------>|
| | | |
| 201 Created | | 201 Created |
skipping to change at page 9, line 24 skipping to change at page 9, line 24
| | | |
| 204 No Content | | 204 No Content |
|<------------------------------------------------| |<------------------------------------------------|
| | | |
Figure 6: Appending partial representation data to upload Figure 6: Appending partial representation data to upload
3) If the connection was interrupted, the client might want to resume 3) If the connection was interrupted, the client might want to resume
the upload, similar to the previous example (Section 3.1). The the upload, similar to the previous example (Section 3.1). The
client retrieves the offset (Section 4.3) to learn the amount of client retrieves the offset (Section 4.3) to learn the amount of
representation data received by the server and then continues representation data processed by the server and then continues
appending the remaining parts to the upload as in the previous step. appending the remaining parts to the upload as in the previous step.
Client Server Client Server
| | | |
| HEAD /uploads/abc | | HEAD /uploads/abc |
|------------------------------------------------>| |------------------------------------------------>|
| | | |
| 204 No Content | | 204 No Content |
| Upload-Offset: Y | | Upload-Offset: Y |
|<------------------------------------------------| |<------------------------------------------------|
skipping to change at page 10, line 5 skipping to change at page 10, line 5
| 204 No Content | | 204 No Content |
|<------------------------------------------------| |<------------------------------------------------|
| | | |
Figure 7: Resuming an interrupted upload Figure 7: Resuming an interrupted upload
4) The request to append the last part of the representation data has 4) The request to append the last part of the representation data has
a "Upload-Complete" field value set to true to indicate the complete a "Upload-Complete" field value set to true to indicate the complete
transfer. Once the remaining representation data is transferred, the transfer. Once the remaining representation data is transferred, the
server processes the entire representation and responds with whatever server processes the entire representation and responds with whatever
the initial request to "/project/123/files" would have produced if it the initial request to "/project/123/files" would have produced if
had received the entire representation, e.g. a "200 (OK)" response. its representation had been fully transferred and processed, e.g. a
"200 (OK)" response.
Client Server Client Server
| | | |
| PATCH /uploads/abc | | PATCH /uploads/abc |
| Upload-Complete: ?1 | | Upload-Complete: ?1 |
| Upload-Offset: Z | | Upload-Offset: Z |
| Content-Type: application/partial-upload | | Content-Type: application/partial-upload |
| | | |
| [remaining representation from offset Z] | | [remaining representation from offset Z] |
|------------------------------------------------>| |------------------------------------------------>|
skipping to change at page 10, line 29 skipping to change at page 10, line 30
|<------------------------------------------------| |<------------------------------------------------|
| | | |
Figure 8: Appending remaining representation data Figure 8: Appending remaining representation data
4. Upload Resource 4. Upload Resource
A resumable upload is enabled through interaction with an upload A resumable upload is enabled through interaction with an upload
resource. When a resumable upload begins, the server is asked to resource. When a resumable upload begins, the server is asked to
create an upload resource through a request to another resource create an upload resource through a request to another resource
(Section 4.2). This upload resource is responsible for handling the (Section 4.2). Using this upload resource, the client can query the
upload of a representation. Using the upload resource, the client upload progress (Section 4.3), append representation data
can query the upload progress (Section 4.3), append representation (Section 4.4), or cancel the upload (Section 4.5). The server is
data (Section 4.4), or cancel the upload (Section 4.5). responsible for persisting the state of the upload resource
(Section 4.1) and updating it as the upload progresses.
An upload resource is specific to the upload of one representation. An upload resource is specific to the upload of one representation.
For uploading multiple representations, multiple upload resources For uploading multiple representations, multiple upload resources
have to be used. have to be used.
The server can clean up an upload resource and make it inaccessible The server can clean up an upload resource and make it inaccessible
immediately after the upload is complete. However, if a client immediately after the upload is complete. However, if a client
didn't receive the last response acknowledging the upload's didn't receive the last response acknowledging the upload's
completion and the upload resource is not available anymore, the completion and the upload resource is not available anymore, the
client cannot verify the upload's state with the server. Therefore, client cannot verify the upload's state with the server. Therefore,
skipping to change at page 11, line 8 skipping to change at page 11, line 10
the upload. the upload.
An upload resource SHOULD be unique. Reuse of a URI for a different An upload resource SHOULD be unique. Reuse of a URI for a different
upload resource SHOULD be avoided in order to reduce the chance of upload resource SHOULD be avoided in order to reduce the chance of
misdirected or corrupted upload resources, as well as the potential misdirected or corrupted upload resources, as well as the potential
security issues described in Section 13. security issues described in Section 13.
4.1. State 4.1. State
The state of an upload consists of the following properties that are The state of an upload consists of the following properties that are
tracked by the upload resource. tracked by the server.
4.1.1. Offset 4.1.1. Offset
The offset is the number of bytes from the representation data that The offset is the number of bytes from the representation data that
have been received, either during the creation of the upload resource have been processed, either during the creation of the upload
(Section 4.2) and by appending to it (Section 4.4). The offset can resource (Section 4.2) or by appending to it (Section 4.4). The
be retrieved from the upload resource (Section 4.3) and is required offset can be retrieved from the upload resource (Section 4.3) and is
when appending representation data (Section 4.4) to synchronize the required when appending representation data (Section 4.4) to
client and resource regarding the amount of transferred synchronize the client and resource regarding the amount of
representation data. transferred representation data.
Representation data received by the upload resource cannot be removed The offset reflects application-level processing for the upload.
again and, therefore, the offset MUST NOT decrease. If the server Data may have been delivered and acknowledged at the transport layer
loses any part of the state, it MUST deactivate the upload resource without yet being reflected in the offset.
and reject further interaction with it.
Representation data processed by the upload resource cannot be
removed again and, therefore, the offset MUST NOT decrease. If the
server loses any part of the state, it MUST deactivate the upload
resource and reject further interaction with it.
The "Upload-Offset" request and response header field conveys the The "Upload-Offset" request and response header field conveys the
offset. "Upload-Offset" is an Item Structured Header Field offset. "Upload-Offset" is an Item Structured Header Field
([STRUCTURED-FIELDS]). Its value is a non-negative Integer ([STRUCTURED-FIELDS]). Its value is a non-negative Integer
(Section 3.3.1 of [STRUCTURED-FIELDS]) and indicates the current (Section 3.3.1 of [STRUCTURED-FIELDS]) and indicates the current
offset as viewed by the message sender. Other values MUST cause the offset as viewed by the message sender. Other values MUST cause the
entire header field to be ignored. entire header field to be ignored.
The "Upload-Offset" header field in responses serves as an The "Upload-Offset" header field in responses serves as an
acknowledgement of the received representation data and as a acknowledgement of the processed representation data and as a
guarantee that no retransmission of it will be necessary. Clients guarantee that no retransmission of it will be necessary. Clients
can use this guarantee to free resources associated to transferred can use this guarantee to free resources associated to transferred
representation data. representation data.
4.1.2. Completeness 4.1.2. Completeness
An upload is incomplete until it is explicitly marked as completed by An upload is incomplete until it is explicitly marked as completed by
the client. After this point, no representation data can be appended the client. After this point, no representation data can be appended
anymore. anymore.
The "Upload-Complete" request and response header field conveys the The "Upload-Complete" request and response header field conveys the
completeness state. "Upload-Complete" is an Item Structured Header completeness state. "Upload-Complete" is an Item Structured Header
Field ([STRUCTURED-FIELDS]). Its value is a Boolean (Section 3.3.6 Field ([STRUCTURED-FIELDS]). Its value is a Boolean (Section 3.3.6
of [STRUCTURED-FIELDS]) and indicates whether the upload is complete of [STRUCTURED-FIELDS]) and indicates whether the upload is complete
or not. Other values MUST cause the entire header field to be or not. Other values MUST cause the entire header field to be
ignored. ignored.
An upload is marked as completed if a request for creating the upload An upload is marked as completed if a request for creating the upload
resource (Section 4.2) or appending to it (Section 4.4) included the resource (Section 4.2) or appending to it (Section 4.4) included the
"Upload-Complete" header field with a true value and the request "Upload-Complete" header field with a true value and the request
content was fully received. content was fully processed.
4.1.3. Length 4.1.3. Length
The length of an upload is the number of bytes of representation data The length of an upload is the number of bytes of representation data
that the client intends to upload. that the client intends to upload.
Even the client might not know the total length of the representation Even the client might not know the total length of the representation
data when starting the transfer, for example, because the data when starting the transfer, for example, because the
representation is taken from a streaming source. However, a client representation is taken from a streaming source. However, a client
SHOULD communicate the length to the upload resource as soon as it SHOULD communicate the length to the server as soon as it becomes
becomes known. There are two different ways for the client to known. There are two different ways for the client to indicate and
indicate and the upload resource to discover the length from requests the server to discover the length from requests for creating the
for creating the upload resource (Section 4.2) or appending to it upload resource (Section 4.2) or appending to it (Section 4.4):
(Section 4.4):
1. If the request includes the "Upload-Complete" field value set to 1. If the request includes the "Upload-Complete" field value set to
true and a valid "Content-Length" header field, the request true and a valid "Content-Length" header field, the request
content is the remaining representation data. The length is then content is the remaining representation data. The length is then
the sum of the current offset (Section 4.1.1) and the "Content- the sum of the current offset (Section 4.1.1) and the "Content-
Length" header field value. Length" header field value.
2. The request can include the "Upload-Length" header field defined 2. The request can include the "Upload-Length" header field defined
below. below.
skipping to change at page 12, line 46 skipping to change at page 13, line 5
If indicators (1) and (2) are both present in the same request, their If indicators (1) and (2) are both present in the same request, their
indicated lengths MUST match. If multiple requests include indicated lengths MUST match. If multiple requests include
indicators, their indicated values MUST match. A server can use the indicators, their indicated values MUST match. A server can use the
problem type [PROBLEM] of "https://iana.org/assignments/http-problem- problem type [PROBLEM] of "https://iana.org/assignments/http-problem-
types#inconsistent-upload-length" (Section 7.3) in responses to types#inconsistent-upload-length" (Section 7.3) in responses to
indicate inconsistent length values. indicate inconsistent length values.
The "Upload-Length" field can be used in response to an offset The "Upload-Length" field can be used in response to an offset
retrieval; see Section 4.3.2. retrieval; see Section 4.3.2.
The upload resource might not know the length until the upload is The server might not know the length until the upload is complete.
complete.
Note that the length and offset values do not determine whether an Note that the length and offset values do not determine whether an
upload is complete. Instead, the client uses the "Upload-Complete" upload is complete. Instead, the client uses the "Upload-Complete"
(Section 4.1.2) header field to indicate that a request completes the (Section 4.1.2) header field to indicate that a request completes the
upload. The offset could match the length, but the upload can still upload. The offset could match the length, but the upload can still
be incomplete. be incomplete.
4.1.4. Limits 4.1.4. Limits
An upload resource MAY enforce one or multiple limits, which are A server MAY enforce one or multiple limits, which are communicated
communicated to the client via the "Upload-Limit" response header to the client via the "Upload-Limit" response header field. "Upload-
field. "Upload-Limit" is a Dictionary Structured Header Field Limit" is a Dictionary Structured Header Field ([STRUCTURED-FIELDS]).
([STRUCTURED-FIELDS]). Its value is a Dictionary (Section 3.2 of Its value is a Dictionary (Section 3.2 of [STRUCTURED-FIELDS]).
[STRUCTURED-FIELDS]). Other values MUST cause the entire header Other values MUST cause the entire header field to be ignored.
field to be ignored.
The following key-value pairs are defined: The following key-value pairs are defined:
max-size: Specifies a maximum size for the representation data, max-size: Specifies a maximum size for the representation data,
counted in bytes. The server might not create an upload resource counted in bytes. The server might not create an upload resource
if the length (Section 4.1.3) deduced from the upload creation if the length (Section 4.1.3) deduced from the upload creation
request is larger than the maximum size. The server might also request is larger than the maximum size. The server might also
deactivate the upload resource if the offset (Section 4.1.1) deactivate the upload resource if the offset (Section 4.1.1)
exceeds the maximum size. The value is an Integer. exceeds the maximum size. The value is an Integer.
min-size: Specifies a minimum size for the representation data, min-size: Specifies a minimum size for the representation data,
counted in bytes. The server might not create an upload resource counted in bytes. The server might not create an upload resource
if the length (Section 4.1.3) deduced from the upload creation if the length (Section 4.1.3) deduced from the upload creation
request is smaller than the minimum size or no length can be request is smaller than the minimum size or no length can be
deduced at all. The value is an Integer. deduced at all. The value is an Integer.
max-append-size: Specifies a maximum size counted in bytes for the max-append-size: Specifies a maximum size counted in bytes for the
request content in a single upload append request (Section 4.4). request content in a single upload append (Section 4.4) or upload
The server might reject requests exceeding this limit. A client creation (Section 4.2) request. The server might reject requests
that is aware of this limit MUST NOT send larger upload append exceeding this limit. A client that is aware of this limit MUST
requests. The value is an Integer. NOT send larger upload append or upload creation requests. The
value is an Integer.
min-append-size: Specifies a minimum size counted in bytes for the min-append-size: Specifies a minimum size counted in bytes for the
request content in a single upload append request (Section 4.4). request content in a single upload append (Section 4.4) or upload
The server might reject requests below this limit. A client that creation (Section 4.2) request. The server might reject requests
is aware of this limit MUST NOT send smaller upload append below this limit. A client that is aware of this limit MUST NOT
requests. The value is an Integer. Requests completing the send smaller upload append or upload creation requests. The value
upload by including the "Upload-Complete: ?1" header field are is an Integer. Requests completing the upload by including the
exempt from this limit. "Upload-Complete: ?1" header field are exempt from this limit.
max-age: Specifies the remaining lifetime of the upload resource in max-age: Specifies the remaining lifetime of the upload resource in
seconds counted from the generation of the response. After the seconds counted from the generation of the response. After the
resource's lifetime is reached, the server might make the upload resource's lifetime is reached, the server might make the upload
resource inaccessible and a client SHOULD NOT attempt to access resource inaccessible and a client SHOULD NOT attempt to access
the upload resource as these requests will likely fail. The value the upload resource as these requests will likely fail. The value
is an Integer. is an Integer.
Clients usually discover limits through the "Upload-Limit" header Clients usually discover limits through the "Upload-Limit" header
field when the upload resource is created (Section 4.2). Throughout field when the upload resource is created (Section 4.2). Throughout
skipping to change at page 14, line 26 skipping to change at page 14, line 30
Receivers of "Upload-Limit" parse the Dictionary as described in Receivers of "Upload-Limit" parse the Dictionary as described in
Section 4.2 of [STRUCTURED-FIELDS]. Where the Dictionary is Section 4.2 of [STRUCTURED-FIELDS]. Where the Dictionary is
successfully parsed, this document places two additional requirements successfully parsed, this document places two additional requirements
on Dictionary members. First, a member with an unknown key MUST be on Dictionary members. First, a member with an unknown key MUST be
ignored. Second, a member with a known key but a value of unexpected ignored. Second, a member with a known key but a value of unexpected
type MUST cause the entire "Upload-Limit" header field to be ignored, type MUST cause the entire "Upload-Limit" header field to be ignored,
or alternatively the complete HTTP message MUST be treated as or alternatively the complete HTTP message MUST be treated as
malformed. malformed.
A server that supports the creation of a resumable upload resource When responding to an "OPTIONS" request, if the resource that is the
(Section 4.2) for a target URI MUST include the "Accept-Patch" target of the request supports the creation of a resumable upload
(Section 3.1 of [PATCH]) header field in response to an "OPTIONS" resource (Section 4.2), the server MUST include the "Accept-Patch"
request for the target URI. If a server supports the creation of (Section 3.1 of [PATCH]) header field in the response. If a server
upload resources for any target URI, it SHOULD include the "Accept- is configured such that all of its resources support the creation of
Patch" header field in response to an "OPTIONS" request for the upload resources with identical limits, it SHOULD include the
target "*" (if this target is supported). The value of the "Accept- "Accept-Patch" header field in response to an "OPTIONS" request for
Patch" header field MUST include the full "application/partial- the target "*" (if this target is supported). The value of the
upload" media type, even if it already contains "*/*" or "Accept-Patch" header field MUST include the full "application/
partial-upload" media type, even if it already contains "*/*" or
"application/*". The "Upload-Limit" header field SHOULD be included "application/*". The "Upload-Limit" header field SHOULD be included
in the response to an "OPTIONS" request if limits apply. in the response to an "OPTIONS" request if limits apply.
A client can use an "OPTIONS" request to discover support for A client can use an "OPTIONS" request to discover whether the
resumable uploads and potential limits before creating an upload resource supports resumable uploads and to learn potential limits
resource. While the values "*/*" and "application/*" in the "Accept- before creating an upload resource. While the values "*/*" and
Patch" response header field indicate the acceptance of the "application/*" in the "Accept-Patch" response header field indicate
"application/partial-upload" in PATCH requests, it does not the acceptance of the "application/partial-upload" in PATCH requests,
necessarily indicate support for all aspects of resumable uploads as it does not necessarily indicate support for all aspects of resumable
defined in this document. To reduce the likelihood of failing uploads as defined in this document. To reduce the likelihood of
requests, the limits announced in an "OPTIONS" response SHOULD NOT be failing requests, the limits announced in an "OPTIONS" response
less restrictive than the limits applied to an upload once the upload SHOULD NOT be less restrictive than the limits applied to an upload
resource has been created, unless the request to create an upload once the upload resource has been created, unless the request to
resource included additional information that warrants different create an upload resource included additional information that
limits. For example, a server might announce a general maximum size warrants different limits. For example, a server might announce a
limit of 1GB, but reduce it to 100MB when the media type indicates an general maximum size limit of 1GB, but reduce it to 100MB when the
image. media type indicates an image.
Servers, including intermediaries, can (and often do) apply Servers, including intermediaries, can (and often do) apply
restrictions on the size of individual request message content. restrictions on the size of individual request message content.
There is no standard mechanism to communicate such existing size There is no standard mechanism to communicate such existing size
restriction. A server that implements one can respond with a 413 restriction. A server that implements one can respond with a "413
Content Too Large status code; see Section 15.5.14 of [HTTP]. (Content Too Large)" status code; see Section 15.5.14 of [HTTP].
Appending to an upload resource, as a series of appends, can be used Appending to an upload resource, as a series of appends, can be used
to upload data up to the "max-size" limit without encountering per- to upload data up to the "max-size" limit without encountering per-
message limits. The "min-append-size" and "max-append-size" limits message limits. Servers might apply restrictions that are smaller
apply to the upload resource. Servers might apply restrictions that than the append limits, which would also result in a failed request.
are smaller than the append limits, which would also result in a
failed request. Clients could deal with such situations by retrying A server responding with a "413 (Content Too Large)" status code as a
an upload append using a smaller size, as long as the new size result of its upload limits SHOULD include the "Upload-Limit" header
resides between "min-append-size" and "max-append-size". Cases where field in this response if possible. This might not be possible if
an append uses "min-append-size" yet fails with a 413 Content Too intermediaries enforce content size restrictions. When a client
Large response might indicate a deployment mismatch that cannot be receives a response with a "413 (Content Too Large)" status code
recovered from. during upload creation (Section 4.2) or append (Section 4.4), it
SHOULD retry the request with a smaller size residing between "min-
append-size" and "max-append-size". If these limits are unknown at
the time of receiving such a response, the client can attempt to
discover them through an "OPTIONS" request. Retrying with the same
request content size will likely yield the same error response.
Cases where the request content size matches the "min-append-size"
limit yet fails with a "413 (Content Too Large)" response might
indicate a deployment mismatch that cannot be recovered from.
4.2. Upload Creation 4.2. Upload Creation
4.2.1. Client Behavior 4.2.1. Client Behavior
A client can start a resumable upload from any request that can carry A client can start a resumable upload from any request that can carry
content by including the "Upload-Complete" header field content by including the "Upload-Complete" header field
(Section 4.1.2). As a consequence, all request methods that allow (Section 4.1.2). As a consequence, all request methods that allow
content are possible, such as "POST", "PUT", and "PATCH". content are possible, such as "POST", "PUT", and "PATCH".
skipping to change at page 16, line 26 skipping to change at page 16, line 38
representation data. The "Content-Type" header field (Section 8.3 of representation data. The "Content-Type" header field (Section 8.3 of
[HTTP]) indicates the media type of the representation. The [HTTP]) indicates the media type of the representation. The
"Content-Encoding" header field (Section 8.4 of [HTTP]) names the "Content-Encoding" header field (Section 8.4 of [HTTP]) names the
content codings applied to the representation. The "Content- content codings applied to the representation. The "Content-
Disposition" header field ([CONTENT-DISPOSITION]) can be used to Disposition" header field ([CONTENT-DISPOSITION]) can be used to
transmit a filename. For this purpose, the "inline" disposition type transmit a filename. For this purpose, the "inline" disposition type
is RECOMMENDED. is RECOMMENDED.
If the client received a final response with a If the client received a final response with a
o "2xx (Successful)" status code and the entire representation data o "2xx (Successful)" status code and the request content contained
was transferred in the request content, the upload is complete and the entire representation data, the upload is complete and the
the response comes from the targeted resource processing the response comes from the resource targeted by the initial request
representation. processing the representation.
o "2xx (Successful)" status code and the entire representation data o "2xx (Successful)" status code and the request content did not
was not transferred in the request content, the "Location" contain the entire representation data, the "Location" response
response header field points the client to the created upload header field points the client to the created upload resource.
resource. The client can continue appending representation data The client can continue appending representation data to it
to it (Section 4.4). (Section 4.4).
o "4xx (Client Error)" status code, the client SHOULD NOT attempt to o "4xx (Client Error)" status code, the client SHOULD NOT attempt to
retry or resume the upload, unless the semantics of the response retry or resume the upload, unless the semantics of the response
allow or recommend the client to retry the request. allow or recommend the client to retry the request.
o "5xx (Server Error)" status code or no final response at all due o "5xx (Server Error)" status code or no final response at all due
to connectivity issues, the client MAY automatically attempt to connectivity issues, the client MAY automatically attempt
upload resumption by retrieving the current offset (Section 4.3) upload resumption by retrieving the current offset (Section 4.3)
if it received the URI of the upload resource in a "104 (Upload if it received the URI of the upload resource in a "104 (Upload
Resumption Supported)" interim response. Resumption Supported)" interim response.
4.2.2. Server Behavior 4.2.2. Server Behavior
Upon receiving a request with the "Upload-Complete" header field, the Upon receiving a request with the "Upload-Complete" header field, the
server can choose to offer resumption support by creating an upload server can choose to offer resumption support for this request by
resource. If so, it SHOULD announce the upload resource by sending creating an upload resource. If so, the server SHOULD announce the
an interim response with the "104 (Upload Resumption Supported)" upload resource by sending an interim response with the "104 (Upload
status code unless the server is not capable of sending interim Resumption Supported)" status code unless the server is not capable
responses. The interim response allows the client to resume the of sending interim responses. The interim response allows the client
upload even if the message exchange gets later interrupted. When to resume the upload even if the message exchange gets later
sent, it MUST include "Location" header field pointing to the upload interrupted. When sent, it MUST include "Location" header field
resource and MUST include the "Upload-Limit" header field with the pointing to the upload resource and MUST include the "Upload-Limit"
corresponding limits (Section 4.1.4) if existing. header field with the corresponding limits (Section 4.1.4) if
existing.
The resource targeted by this initial request is responsible for The resource targeted by this initial request is responsible for
processing the representation data transferred in the resumable processing the representation data transferred in the resumable
upload according to the method and header fields in the initial upload according to the method and header fields in the initial
request, while the upload resource enables resuming the transfer. request. The upload resource, on the other hand, enables resuming
the transfer.
If the "Upload-Complete" request header field is set to true, the If the "Upload-Complete" request header field is set to true, the
client intends to transfer the entire representation data in one client intends to transfer the entire representation data in one
request. If the request content was fully received, no resumable request. If the request content was fully processed, no resumable
upload is needed and the resource proceeds to process the request and upload is needed and the server proceeds to process the request and
generate a response. generate a response.
If the "Upload-Complete" header field is set to false, the client If the "Upload-Complete" header field is set to false, the client
intends to transfer the representation over multiple requests. If intends to transfer the representation over multiple requests. If
the request content was fully received, the server MUST include the the request content was fully processed, the server MUST include the
"Location" response header field pointing to the upload resource and "Location" response header field pointing to the upload resource and
MUST include the "Upload-Limit" header field with the corresponding MUST include the "Upload-Limit" header field with the corresponding
limits if existing. Servers are RECOMMENDED to use the "201 limits if existing. Servers are RECOMMENDED to use the "201
(Created)" status code. (Created)" status code.
The server MUST record the length according to Section 4.1.3 if the The server MUST record the length according to Section 4.1.3 if the
"Upload-Length" or "Upload-Complete: ?1" header fields are included "Upload-Length" or "Upload-Complete: ?1" header fields are included
in the request. in the request.
While the request content is being received, the server MAY send While the request content is being processed, the server MAY send
multiple interim responses with a "104 (Upload Resumption Supported)" multiple interim responses with a "104 (Upload Resumption Supported)"
status code and the "Upload-Offset" header field set to the current status code and the "Upload-Offset" header field set to the current
offset to inform the client about the upload progress. offset to inform the client about the upload progress.
Where a response requires a "Location" header field to be included, Where a response requires a "Location" header field to be included,
all interim and final response messages for the same request MUST all interim and final response messages for the same request MUST
contain an identical "Location" value. However, final responses contain an identical "Location" value. However, final responses
including the "Upload-Complete: ?1" header field are exempt from this including the "Upload-Complete: ?1" header field are exempt from this
requirement because they are the result of processing the transferred requirement because they are the result of processing the transferred
representation and the "Location" value does not necessarily representation and the "Location" value does not necessarily
represent the upload location. Where the "Location" value is represent the upload location. Where the "Location" value is
expected to be identical across multiple messages, clients SHOULD expected to be identical across multiple messages, clients SHOULD
verify this. If verification fails, clients SHOULD abort the current verify this. If verification fails, clients SHOULD abort the current
request and cancel the upload (Section 4.5). request and cancel the upload (Section 4.5).
The server might not receive the entire request content when the The server might not process the entire request content when the
upload is interrupted, for example because of dropped connection or upload is interrupted, for example because of dropped connection or
canceled request. In this case, the server SHOULD append as much of canceled request. In this case, the server SHOULD append as much of
the request content as possible to the upload resource, allowing the the request content as possible to the upload resource, allowing the
client to resume the upload from where it was interrupted. In client to resume the upload from where it was interrupted. In
addition, the upload resource MUST NOT be considered complete then. addition, the upload resource MUST NOT be considered complete then.
4.2.3. Examples 4.2.3. Examples
A) The following example shows an upload creation, where the entire A) The following example shows an upload creation, where the entire
123456789 bytes are transferred in the initial request. The server 123456789 bytes are transferred in the initial request. The server
skipping to change at page 18, line 38 skipping to change at page 19, line 4
HTTP/1.1 104 Upload Resumption Supported HTTP/1.1 104 Upload Resumption Supported
Upload-Offset: 23456789 Upload-Offset: 23456789
HTTP/1.1 200 OK HTTP/1.1 200 OK
Location: https://example.com/upload/b530ce8ff Location: https://example.com/upload/b530ce8ff
Upload-Limit: max-size=1234567890 Upload-Limit: max-size=1234567890
Content-Type: application/json Content-Type: application/json
{"attachmentId": "b530ce8ff"} {"attachmentId": "b530ce8ff"}
B) The following example shows an upload creation, where only the B) The following example shows an upload creation, where only the
first 23456789 bytes of a 123456789 bytes upload are transferred. first 23456789 bytes of a 123456789 bytes upload are transferred.
The server acknowledges the received representation data and that the The server acknowledges the processed representation data and that
upload is not complete yet. The client can continue appending data. the upload is not complete yet. The client can continue appending
data.
POST /upload HTTP/1.1 POST /upload HTTP/1.1
Host: example.com Host: example.com
Upload-Complete: ?0 Upload-Complete: ?0
Content-Length: 23456789 Content-Length: 23456789
Upload-Length: 123456789 Upload-Length: 123456789
[partial content (23456789 bytes)] [partial content (23456789 bytes)]
HTTP/1.1 104 Upload Resumption Supported HTTP/1.1 104 Upload Resumption Supported
Location: https://example.com/upload/3fd4994ad Location: https://example.com/upload/3fd4994ad
HTTP/1.1 201 Created HTTP/1.1 201 Created
Location: https://example.com/upload/3fd4994ad Location: https://example.com/upload/3fd4994ad
Upload-Limit: max-size=1234567890 Upload-Limit: max-size=1234567890
C) The following example shows an upload creation, where the server C) The following example shows an upload creation, where the server
responds with a 5xx status code. Thanks to the interim response responds with a 5xx status code. Thanks to the interim response
containing the upload resource URI, the client can resume the upload. containing the upload resource URI, the client can resume the upload.
skipping to change at page 19, line 29 skipping to change at page 19, line 43
Upload-Length: 123456789 Upload-Length: 123456789
[content (123456789 bytes)] [content (123456789 bytes)]
HTTP/1.1 104 Upload Resumption Supported HTTP/1.1 104 Upload Resumption Supported
Location: https://example.com/upload/0587fa44b Location: https://example.com/upload/0587fa44b
HTTP/1.1 500 Internal Server Error HTTP/1.1 500 Internal Server Error
D) The following example shows an upload creation being rejected by D) The following example shows an upload creation being rejected by
the server because uploads to the target resource are not allowed. the server because uploads to the targetted resource are not allowed.
The client cannot continue the upload. The client cannot continue the upload.
POST /upload-not-allowed HTTP/1.1 POST /upload-not-allowed HTTP/1.1
Host: example.com Host: example.com
Upload-Complete: ?1 Upload-Complete: ?1
Content-Length: 123456789 Content-Length: 123456789
Upload-Length: 123456789 Upload-Length: 123456789
[content (123456789 bytes)] [content (123456789 bytes)]
HTTP/1.1 405 Method Not Allowed HTTP/1.1 405 Method Not Allowed
4.3. Offset Retrieval 4.3. Offset Retrieval
4.3.1. Client Behavior 4.3.1. Client Behavior
If the client wants to resume the upload after an interruption, it If the client wants to resume the upload after an interruption, it
has to know the amount of representation data received by the upload has to know the amount of representation data processed by the upload
resource so far. It can fetch the offset by sending a "HEAD" request resource so far. It can fetch the offset by sending a "HEAD" request
to the upload resource. Upon a successful response, the client can to the upload resource. Upon a successful response, the client can
continue the upload by appending representation data (Section 4.4) continue the upload by appending representation data (Section 4.4)
starting at the offset indicated by the "Upload-Offset" response starting at the offset indicated by the "Upload-Offset" response
header field. header field.
The offset can be less than or equal to the number of bytes of The offset can be less than or equal to the number of bytes of
representation data that the client has already sent. The client MAY representation data that the client has already sent. The client is
reject an offset which is greater than the number of bytes it has expected to handle backtracking of a reasonable length. On the other
already sent during this upload by not continuing the upload and hand, the offset can be greater than the amount of sent
canceling the upload resource (Section 4.5). The client is expected representation data if the upload resource obtained additional
to handle backtracking of a reasonable length. If the offset is representation data on behalf of the client. If the client is not
invalid for this upload, or if the client cannot backtrack to the able to provide the representation data at the given offset, the
offset and reproduce the same representation data it has already upload MUST be considered a failure. The client then MUST NOT
sent, the upload MUST be considered a failure. The client then MUST continue the upload and SHOULD cancel the upload (Section 4.5).
NOT continue the upload and SHOULD cancel the upload (Section 4.5).
The client MUST NOT perform offset retrieval while creation The client MUST NOT perform offset retrieval while creation
(Section 4.2) or appending (Section 4.4) is in progress as this can (Section 4.2) or appending (Section 4.4) is in progress as this can
cause the previous request to be terminated by the server as cause the previous request to be terminated by the server as
described in Section 4.6. described in Section 4.6.
If the client received a response with a If the client received a response with a
o "2xx (Successful)" status code, the client can continue appending o "2xx (Successful)" status code, the client can continue appending
representation data to it (Section 4.4) if the upload is not representation data to it (Section 4.4) if the upload is not
skipping to change at page 22, line 4 skipping to change at page 22, line 17
HEAD /upload/a9edb781b HTTP/1.1 HEAD /upload/a9edb781b HTTP/1.1
Host: example.com Host: example.com
HTTP/1.1 204 No Content HTTP/1.1 204 No Content
Upload-Complete: ?1 Upload-Complete: ?1
Upload-Offset: 100000000 Upload-Offset: 100000000
Upload-Length: 100000000 Upload-Length: 100000000
Cache-Control: no-store Cache-Control: no-store
4.4. Upload Append 4.4. Upload Append
4.4.1. Client Behavior 4.4.1. Client Behavior
A client can continue the upload and append representation data by A client can continue the upload and append representation data by
sending a "PATCH" request with the "application/partial-upload" media sending a "PATCH" request with the "application/partial-upload" media
type (Section 6) to the upload resource. The request content is the type (Section 6) to the upload resource. The request content is the
representation data to append. representation data to append.
The client MUST indicate the offset of the request content inside the The client MUST indicate the offset of the request content inside the
representation data by including the "Upload-Offset" request header representation data by including the "Upload-Offset" header field.
field. To ensure that the upload resource will accept the request, To ensure that the upload resource will accept the request, the
the offset SHOULD be taken from an immediate previous response for offset SHOULD be taken from an immediate previous response for
retrieving the offset (Section 4.3) or appending representation data retrieving the offset (Section 4.3) or appending representation data
(Section 4.4). (Section 4.4).
The request MUST include the "Upload-Complete" header field. Its The request MUST include the "Upload-Complete" header field. Its
value is true in two cases: value is true in two cases:
o the request has content that is the end of the representation o the request has content that is the end of the representation
data. Once the content is fully received by the server, the data. Once the content is fully processed by the server, the
upload is complete. upload is complete.
o the request has no content. Once the request is processed by the o the request has no content. Once the request is processed by the
server, the upload is complete. This usage requires the full server, the upload is complete. This usage requires the full
representation data to have been received via prior requests. representation data to have been processed during prior requests.
If the client received a final response with the "Upload-Complete: If the client received a final response with the "Upload-Complete:
?1" header field, the upload is complete and the corresponding ?1" header field, the upload is complete and the corresponding
response comes from the resource processing the representation response comes from the resource processing the representation
according to the initial request (see Section 4.2). Note that the according to the initial request (see Section 4.2). Note that the
status code does not necessary indicate success. "4xx (Client Error)" status code does not necessary indicate success. "4xx (Client Error)"
or "5xx (Server Error)" status codes indicate in this case that the or "5xx (Server Error)" status codes indicate in this case that the
representation was fully transmitted, but an error occurred while representation was fully transmitted, but an error occurred while
processing it. Resuming the upload would not resolve this error. processing it. Resuming the upload would not resolve this error.
skipping to change at page 23, line 15 skipping to change at page 23, line 30
o For a "5xx (Server Error)" status code, the client MAY o For a "5xx (Server Error)" status code, the client MAY
automatically attempt upload resumption by retrieving the current automatically attempt upload resumption by retrieving the current
offset (Section 4.3). offset (Section 4.3).
If no final response was received at all due to connectivity issues, If no final response was received at all due to connectivity issues,
the client MAY automatically attempt upload resumption by retrieving the client MAY automatically attempt upload resumption by retrieving
the current offset (Section 4.3). the current offset (Section 4.3).
4.4.2. Server Behavior 4.4.2. Server Behavior
An upload resource applies a "PATCH" request with the "application/ A server applies a "PATCH" request with the "application/partial-
partial-upload" media type (Section 6) by appending the patch upload" media type (Section 6) to an upload resource by appending the
document in the request content to the upload resource. patch document in the request content.
The server might not receive the entire patch document when the The server might not process the entire patch document when the
upload is interrupted, for example because of a dropped connection or upload is interrupted, for example because of a dropped connection or
canceled request. In this case, the server SHOULD append as much of canceled request. In this case, the server SHOULD append as much of
the patch document as possible to the upload resource, starting at the patch document as possible to the upload resource, starting at
its beginning and without discontinuities. Appending a continuous its beginning and without discontinuities. Appending a continuous
section starting at the patch document's beginning constitutes a section starting at the patch document's beginning constitutes a
successful PATCH as defined in Section 2 of [PATCH]. Saving the successful PATCH as defined in Section 2 of [PATCH]. Saving the
received data allows the client to resume the upload from where it processed data allows the client to resume the upload from where it
was interrupted. In addition, the upload resource MUST NOT be was interrupted. In addition, the upload resource MUST NOT be
considered complete then. considered complete then.
If the "Upload-Offset" request header field value does not match the If the "Upload-Offset" request header field value does not match the
current offset (Section 4.1.1), the upload resource MUST reject the current offset (Section 4.1.1), the server MUST reject the request
request with a "409 (Conflict)" status code. The response MUST with a "409 (Conflict)" status code. The response MUST include the
include the correct offset in the "Upload-Offset" header field. The correct offset in the "Upload-Offset" header field. The response can
response can use the problem type [PROBLEM] of use the problem type [PROBLEM] of "https://iana.org/assignments/http-
"https://iana.org/assignments/http-problem-types#mismatching-upload- problem-types#mismatching-upload-offset" (Section 7.1).
offset" (Section 7.1).
If the upload is already complete (Section 4.1.2), the server MUST If the upload is already complete (Section 4.1.2), the server MUST
NOT modify the upload resource and MUST reject the request. The NOT modify the upload resource and MUST reject the request. The
choice of response depends on the nature of the upload request and choice of response depends on the nature of the upload request and
server state, including but not limited to: server state, including but not limited to:
o If the client attempted to append a non-zero length document, the o If the client attempted to append a non-zero length document, the
server MUST treat this as an inconsistent length failure. The server MUST treat this as an inconsistent length failure. The
server can use the problem type [PROBLEM] of server can use the problem type [PROBLEM] of
"https://iana.org/assignments/http-problem-types#inconsistent- "https://iana.org/assignments/http-problem-types#inconsistent-
skipping to change at page 24, line 15 skipping to change at page 24, line 31
indicate the location of the completed upload. The server can indicate the location of the completed upload. The server can
use the problem type [PROBLEM] of use the problem type [PROBLEM] of
"https://iana.org/assignments/http-problem-types#completed- "https://iana.org/assignments/http-problem-types#completed-
upload" (Section 7.2) in the response. upload" (Section 7.2) in the response.
* If the server has not retained knowledge of the upload * If the server has not retained knowledge of the upload
resource, a "404 (Not Found)" status code can be used. resource, a "404 (Not Found)" status code can be used.
If the "Upload-Complete" request header field is set to true, the If the "Upload-Complete" request header field is set to true, the
client intends to transfer the remaining representation data in one client intends to transfer the remaining representation data in one
request. If the request content was fully received, the upload is request. If the request content was fully processed, the upload is
marked as complete and the upload resource SHOULD generate the marked as complete and the server SHOULD generate the response that
response that matches what the resource, that was targeted by the matches what the resource, that was targeted by the initial upload
initial upload creation (Section 4.2), would have generated if it had creation (Section 4.2), would have generated if it had processed the
received the entire representation in the initial request. However, entire representation in the initial request. However, the response
the response MUST include the "Upload-Complete" header field with a MUST include the "Upload-Complete" header field with a true value,
true value, allowing clients to identify whether a response, in allowing clients to identify whether a response, in particular error
particular error responses, is related to the resumable upload itself responses, is related to the resumable upload itself or the
or the processing of the upload representation. processing of the uploaded representation.
If the "Upload-Complete" request header field is set to false, the If the "Upload-Complete" request header field is set to false, the
client intends to transfer the remaining representation over multiple client intends to transfer the remaining representation data over
requests. If the request content was fully received, the upload multiple requests. If the request content was fully processed, the
resource acknowledges the appended data by sending a "2xx server acknowledges the appended data by sending a "2xx (Successful)"
(Successful)" response with the "Upload-Complete" header field set to response with the "Upload-Complete" header field set to false.
false.
The server MUST record the length according to Section 4.1.3 if the The server MUST record the length according to Section 4.1.3 if the
"Upload-Length" or "Upload-Complete" header fields are included in "Upload-Length" or "Upload-Complete" header fields are included in
the request. If the length is known, the server MUST prevent the the request. If the length is known, the server MUST prevent the
offset from exceeding the upload length by rejecting the request once offset from exceeding the upload length by rejecting the request once
the offset exceeds the length, marking the upload resource invalid the offset exceeds the length, marking the upload resource invalid
and rejecting any further interaction with it. It is not sufficient and rejecting any further interaction with it. It is not sufficient
to rely on the "Content-Length" header field for enforcement because to rely on the "Content-Length" header field for enforcement because
the header field might not be present. this header field might not be present.
While the request content is being received, the server SHOULD send While the request content is being processed, the server SHOULD send
interim responses with a "104 (Upload Resumption Supported)" status interim responses with a "104 (Upload Resumption Supported)" status
code and the "Upload-Offset" header field set to the current offset code and the "Upload-Offset" header field set to the current offset
to inform the client about the upload progress. These interim to inform the client about the upload progress. These interim
responses MUST NOT include the "Location" header field. responses MUST NOT include the "Location" header field.
4.4.3. Examples 4.4.3. Examples
A) The following example shows an upload append request. The client A) The following example shows an upload append request. The client
transfers the next 23456789 bytes at an offset of 23456789 and does transfers the next 3456789 bytes at an offset of 20000000 and does
not indicate that the upload is then completed. The server generates not indicate that the upload is then completed. The server generates
one interim response and finally acknowledges the new offset: one interim response, when the offset reached 21728394 bytes, and
finally acknowledges the new offset:
PATCH /upload/37a504d87 HTTP/1.1 PATCH /upload/37a504d87 HTTP/1.1
Host: example.com Host: example.com
Upload-Complete: ?0 Upload-Complete: ?0
Upload-Offset: 23456789 Upload-Offset: 20000000
Content-Length: 23456789 Content-Length: 3456789
Content-Type: application/partial-upload Content-Type: application/partial-upload
[content (23456789 bytes)] [content (3456789 bytes)]
HTTP/1.1 104 Upload Resumption Supported HTTP/1.1 104 Upload Resumption Supported
Upload-Offset: 35185184 Upload-Offset: 21728394
HTTP/1.1 204 No Content HTTP/1.1 204 No Content
Upload-Complete: ?0 Upload-Complete: ?0
B) The next example shows an upload append, where the client B) The next example shows an upload append, where the client
transfers the remaining 4567890 bytes and completes the upload with a transfers the remaining 4567890 bytes and completes the upload with a
length of 1234567890 bytes. The server processes the uploaded length of 1234567890 bytes. The server processes the uploaded
representation and generates the responding response, in this example representation and generates the corresponding response, in this
containing extracted meta data: example containing extracted meta data:
PATCH /upload/d38d6ffe8 HTTP/1.1 PATCH /upload/d38d6ffe8 HTTP/1.1
Host: example.com Host: example.com
Upload-Complete: ?1 Upload-Complete: ?1
Upload-Offset: 1230000000 Upload-Offset: 1230000000
Content-Length: 4567890 Content-Length: 4567890
Content-Type: application/partial-upload Content-Type: application/partial-upload
[content (4567890 bytes)] [content (4567890 bytes)]
HTTP/1.1 200 OK HTTP/1.1 200 OK
Upload-Complete: ?1 Upload-Complete: ?1
Content-Type: application/json Content-Type: application/json
{ {
"metadata": { "metadata": {
[...] [...]
} }
} }
skipping to change at page 26, line 4 skipping to change at page 26, line 15
Upload-Complete: ?1 Upload-Complete: ?1
Content-Type: application/json Content-Type: application/json
{ {
"metadata": { "metadata": {
[...] [...]
} }
} }
4.5. Upload Cancellation 4.5. Upload Cancellation
4.5.1. Client Behavior 4.5.1. Client Behavior
If the client wants to terminate the transfer without the ability to If the client wants to terminate the transfer without the ability to
resume, it can send a "DELETE" request to the upload resource. Doing resume, it can send a "DELETE" request to the upload resource. Doing
so is an indication that the client is no longer interested in so is an indication that the client is no longer interested in
continuing the upload, and that the server can release any resources continuing the upload, and that the server can release any resources
associated with it. associated with it.
4.5.2. Server Behavior 4.5.2. Server Behavior
Upon receiving a "DELETE" request, the server SHOULD deactivate the Upon receiving a "DELETE" request, the server SHOULD deactivate the
upload resource. upload resource.
The server SHOULD terminate any in-flight requests to the upload The server SHOULD terminate any in-flight requests to the upload
resource before sending the response by abruptly terminating their resource before sending the response by abruptly terminating their
HTTP connection(s) or stream(s) as described in Section 4.6. HTTP connection(s) or stream(s) as described in Section 4.6.
The resource SHOULD NOT generate a response with the "301 (Moved The server SHOULD NOT generate a response with the "301 (Moved
Permanently)" and "302 (Found)" status codes because clients might Permanently)" and "302 (Found)" status codes because clients might
follow the redirect without preserving the "DELETE" method. follow the redirect without preserving the "DELETE" method.
4.5.3. Example 4.5.3. Example
The following example shows an upload cancellation: The following example shows an upload cancellation:
DELETE /upload/5688a431c HTTP/1.1 DELETE /upload/5688a431c HTTP/1.1
Host: example.com Host: example.com
skipping to change at page 27, line 10 skipping to change at page 27, line 22
data loss and corruption from concurrent requests to append data loss and corruption from concurrent requests to append
representation data (Section 4.4) and/or cancellation (Section 4.5) representation data (Section 4.4) and/or cancellation (Section 4.5)
to the same upload resource. In addition, the server MUST NOT send to the same upload resource. In addition, the server MUST NOT send
outdated information in responses when retrieving the offset outdated information in responses when retrieving the offset
(Section 4.3). This means that the offset sent by the server MUST be (Section 4.3). This means that the offset sent by the server MUST be
accepted in a subsequent request to append representation data if no accepted in a subsequent request to append representation data if no
other request to append representation data or cancel was received in other request to append representation data or cancel was received in
the meantime. In other words, clients have to be able to use the meantime. In other words, clients have to be able to use
received offsets. received offsets.
The RECOMMENDED approach is as follows: If an upload resource The RECOMMENDED approach is as follows: If a server receives a new
receives a new request to retrieve the offset (Section 4.3), append request to retrieve the offset (Section 4.3), append representation
representation data (Section 4.4), or cancel the upload (Section 4.5) data (Section 4.4), or cancel the upload (Section 4.5) while a
while a previous request for creating the upload (Section 4.2) or previous request for creating the upload (Section 4.2) or appending
appending representation data (Section 4.4) is still ongoing, the representation data (Section 4.4) to the same upload resource is
resource SHOULD prevent race conditions, data loss, and corruption by still ongoing, the server SHOULD prevent race conditions, data loss,
terminating the previous request before processing the new request. and corruption by terminating the previous request before processing
Due to network delay and reordering, the resource might still be the new request. Due to network delay and reordering, the server
receiving representation data from an ongoing transfer for the same might still be receiving representation data from an ongoing transfer
upload resource, which in the client's perspective has failed. Since for the same upload resource, which in the client's perspective has
the client is not allowed to perform multiple transfers in parallel, failed. Since the client is not allowed to perform multiple
the upload resource can assume that the previous attempt has already transfers for the same upload resource in parallel, the server can
failed. Therefore, the server MAY abruptly terminate the previous assume that the previous attempt has already failed. Therefore, the
HTTP connection or stream. server MAY abruptly terminate the previous HTTP connection or stream.
Since implementing this approach is not always technically possible Since implementing this approach is not always technically possible
or feasible, other measures can be considered as well. A simpler or feasible, other measures can be considered as well. A simpler
approach is that the server only processes a new request to retrieve approach is that the server only processes a new request to retrieve
the offset (Section 4.3), append representation data (Section 4.4), the offset (Section 4.3), append representation data (Section 4.4),
or cancellation (Section 4.5) once all previous requests have been or cancellation (Section 4.5) once all previous requests have been
processed. This effectively implements exclusive access to the processed. This effectively implements exclusive access to the
upload resource through an access lock. However, since network upload resource through an access lock. However, since network
interruptions can occur in ways that cause the request to hang from interruptions can occur in ways that cause the request to hang from
the server's perspective, it might take the server significant time the server's perspective, it might take the server significant time
skipping to change at page 27, line 47 skipping to change at page 28, line 12
recommended approach is to terminate previous requests to enable recommended approach is to terminate previous requests to enable
quick resumption of uploads. quick resumption of uploads.
5. Status Code 104 (Upload Resumption Supported) 5. Status Code 104 (Upload Resumption Supported)
The "104 (Upload Resumption Supported)" status code is can be used The "104 (Upload Resumption Supported)" status code is can be used
for two purposes: for two purposes:
o When responding to requests to create uploads, an interim response o When responding to requests to create uploads, an interim response
with the "104 (Upload Resumption Supported)" status code can be with the "104 (Upload Resumption Supported)" status code can be
sent to indicate the server's support for resumable uploads, as sent to indicate the resource's support for resumable uploads, as
well as the URI and limits of the corresponding upload resource in well as the URI and limits of the corresponding upload resource in
the "Location" and "Upload-Limit" header fields, respectively (see the "Location" and "Upload-Limit" header fields, respectively (see
Section 4.2). This notifies the client early about the ability to Section 4.2). This notifies the client early about the ability to
resume the upload in case of network interruptions. resume the upload in case of network interruptions.
o While processing the content of a request to append representation o While processing the content of a request to append representation
data or create an upload, the server can regularly send interim data or create an upload, the server can regularly send interim
responses with the "104 (Upload Resumption Supported)" status code responses with the "104 (Upload Resumption Supported)" status code
to indicate the current upload progress in the "Upload-Offset" to indicate the current upload progress in the "Upload-Offset"
header field (see Section 4.2 and Section 4.4). This allows the header field (see Section 4.2 and Section 4.4). This allows the
client to show more accurate progress information about the amount client to show more accurate progress information about the amount
of data received by the server. In addition, clients can use this of data processed by the server. In addition, clients can use
information to release representation data that was buffered, this information to release representation data that was buffered,
knowing that it doesn't have to be re-transmitted. knowing that it doesn't have to be re-transmitted.
When creating or appending resumable uploads, the client can generate When creating or appending resumable uploads, the client can generate
a 100-continue expectation because it wants an indication that the a 100-continue expectation because it wants an indication that the
server is willing to accept the upload. The client MAY treat an resource is willing to accept the upload. The client MAY treat an
interim response with the "104 (Upload Resumption Supported)" status interim response with the "104 (Upload Resumption Supported)" status
code as fulfilling the 100-continue expectation and start sending the code as fulfilling the 100-continue expectation and start sending the
request content. However, the server MUST NOT omit the "100 request content. However, the server MUST NOT omit the "100
(Continue)" response because it has sent an interim response with the (Continue)" response because it has sent an interim response with the
"104 (Upload Resumption Supported)" status code. "104 (Upload Resumption Supported)" status code.
6. Media Type application/partial-upload 6. Media Type application/partial-upload
The "application/partial-upload" media type describes a contiguous The "application/partial-upload" media type describes a contiguous
block from the representation data that should be uploaded to a block from the representation data that should be uploaded to a
skipping to change at page 31, line 6 skipping to change at page 31, line 20
10.1. Representation Digests 10.1. Representation Digests
Representation digests help verify the integrity of the entire Representation digests help verify the integrity of the entire
representation data that has been uploaded so far, which might representation data that has been uploaded so far, which might
stretch across multiple requests. stretch across multiple requests.
If the client knows the integrity digest of the entire representation If the client knows the integrity digest of the entire representation
data before creating an upload resource, it can include the "Repr- data before creating an upload resource, it can include the "Repr-
Digest" header field when creating an upload (Section 4.2). Once the Digest" header field when creating an upload (Section 4.2). Once the
upload is completed, the server can compute the integrity digest of upload is completed, the server can compute the integrity digest of
the received representation data and compare it to the provided the representation data and compare it to the provided digest. If
digest. If the digests don't match, the server SHOULD consider the the digests don't match, the server SHOULD consider the upload
upload failed, not process the representation further, and signal the failed, not process the representation further, and signal the
failure to the client. This way, the integrity of the entire failure to the client. This way, the integrity of the entire
representation data can be protected. representation data can be protected.
Alternatively, when creating an upload (Section 4.2), the client can Alternatively, when creating an upload (Section 4.2), the client can
ask the server to compute and return the integrity digests using a ask the server to compute and return the integrity digests using a
"Want-Repr-Digest" field conveying the preferred algorithms. The "Want-Repr-Digest" field conveying the preferred algorithms. The
response SHOULD include at least one of the requested digests, but response SHOULD include at least one of the requested digests, but
might not include it. The server SHOULD compute the representation might not include it. The server SHOULD compute the representation
digests using the preferred algorithms once the upload is complete digests using the preferred algorithms once the upload is complete
and include the corresponding "Repr-Digest" header field in the and include the corresponding "Repr-Digest" header field in the
skipping to change at page 31, line 37 skipping to change at page 31, line 51
even before the upload is fully completed. even before the upload is fully completed.
10.2. Content Digests 10.2. Content Digests
Content digests help verify the integrity of the content in an Content digests help verify the integrity of the content in an
individual request. individual request.
If the client knows the integrity digest of the content from an If the client knows the integrity digest of the content from an
upload creation (Section 4.2) or upload appending (Section 4.4) upload creation (Section 4.2) or upload appending (Section 4.4)
request, it can include the "Content-Digest" header field in the request, it can include the "Content-Digest" header field in the
request. Once the content has been received, the server can compute request. Once the request is complete, the server can compute the
the integrity digest of the received content and compare it to the integrity digest of the content and compare it to the provided
provided digest. If the digests don't match the server SHOULD digest. If the digests don't match the server SHOULD consider the
consider the transfer failed, not append the content to the upload transfer failed, not append the content to the upload resource, and
resource, and signal the failure to the client. This way, the signal the failure to the client. This way, the integrity of an
integrity of an individual request can be protected. individual request can be protected.
11. Responses to Uploads 11. Responses to Uploads
HTTP uploads often not only transfer a representation to the server HTTP uploads often not only transfer a representation to the server
but also send back information to the client. For resumable uploads, but also send back information to the client. For resumable uploads,
this works similarly to conventional HTTP uploads. The server can this works similarly to conventional HTTP uploads. The server can
include information in the response to the request that transferred include information in the response to the request that transferred
the remaining representation data and included the "Upload-Complete: the remaining representation data and included the "Upload-Complete:
?1" header field. Clients can regard this response as the final ?1" header field. Clients can regard this response as the final
response for the entire upload, as detailed in Section 4.2 and response for the entire upload, as detailed in Section 4.2 and
Section 4.4. Section 4.4.
However, due to network interruptions, the upload resource might However, due to network interruptions, the server might process the
receive the remaining representation data, complete the upload, and remaining representation data, complete the upload, and send a
send a response to the client, which then does not receive the response to the client, which then does not receive the response.
response. The client can learn that the upload is complete by The client can learn that the upload is complete by retrieving its
retrieving its state (Section 4.3), but resumable uploads as defined state (Section 4.3), but resumable uploads as defined in this
in this document do not offer functionality to recover the missed document do not offer functionality to recover the missed response.
response.
To address this issue, the server can send the desired information in To address this issue, the server can send the desired information in
header fields, which are included in both the final response and header fields, which are included in both the final response and
responses when the client fetches the upload state via a HEAD request responses when the client fetches the upload state via a HEAD request
(Section 4.3). This way, the client can retrieve the information (Section 4.3). This way, the client can retrieve the information
from the header even if it failed to receive the final response. If from the header even if it failed to receive the final response. If
the piece of information is too large for header fields, the server the piece of information is too large for header fields, the server
could make it available as a separate resource for retrieval and could make it available as a separate resource for retrieval and
point the client to its URI in an appropriate header field. point the client to its URI in an appropriate header field.
12. Upload Strategies 12. Upload Strategies
The definition of the upload creation request (Section 4.2) provides The definition of the upload creation request (Section 4.2) provides
the client with flexibility to choose whether the representation data the client with flexibility to choose whether the representation data
is fully or partially transferred in the first request, or if no is fully or partially transferred in the first request, or if no
representation data is included at all. Which behavior is best representation data is included at all. Which behavior is best
largely depends on the client's capabilities, its intention to avoid largely depends on the client's capabilities, its desire to avoid
data re-transmission, and its knowledge about the server's support data re-transmission, and its knowledge about the resource's support
for resumable uploads. for resumable uploads.
The following subsections describe two typical upload strategies that The following subsections describe two typical upload strategies that
are suited for common environments. Note that these modes are never are suited for common environments. Note that these modes are never
explicitly communicated to the server and clients are not required to explicitly communicated to the server and clients are not required to
stick to one strategy, but can mix and adapt them to their needs. stick to one strategy, but can mix and adapt them to their needs.
12.1. Optimistic Upload Creation 12.1. Optimistic Upload Creation
An "optimistic upload creation" can be used independent of the An "optimistic upload creation" can be used independent of the
client's knowledge about the server's support for resumable uploads. client's knowledge about the resource's support for resumable
However, the client must be capable of handling and processing uploads. However, the client must be capable of handling and
interim responses. An upload creation request then includes the full processing interim responses. An upload creation request then
representation data because the client anticipates that it will be includes the full representation data because the client anticipates
transferred without interruptions or resumed if an interruption that it will be transferred without interruptions or resumed if an
occurs. interruption occurs.
The benefit of this method is that if the upload creation request The benefit of this method is that if the upload creation request
succeeded, the representation data was transferred in a single succeeded, the representation data was transferred in a single
request without additional round trips. request without additional round trips.
A possible drawback is that the client might be unable to resume an A possible drawback is that the client might be unable to resume an
upload. If an upload is interrupted before the client receives a upload. If an upload is interrupted before the client receives a
"104 (Upload Resumption Supported)" interim response with the upload "104 (Upload Resumption Supported)" interim response with the upload
resource's URI, the client cannot resume that upload due to the resource's URI, the client cannot resume that upload due to the
missing URI. The interim response might not be received if the missing URI. The interim response might not be received if the
interruption happens too early in the message exchange, the server interruption happens too early in the message exchange, the resource
does not support resumable uploads at all, the server does not targeted in the initial request does not support resumable uploads,
support sending the "104 (Upload Resumption Supported)" interim the server is not capable of sending the "104 (Upload Resumption
response, or an intermediary dropped the interim response. Without a Supported)" interim response, or an intermediary dropped the interim
104 response, the client needs to either treat the upload as failed response. Without a 104 response, the client needs to either treat
or retry the entire upload creation request if this is allowed by the the upload as failed or retry the entire upload creation request if
application. this is allowed by the application.
A client might wait for a limited duration to receive a 104 (Upload A client might wait for a limited duration to receive a 104 (Upload
Resumption Supported) interim response before starting to transmit Resumption Supported) interim response before starting to transmit
the request content. This way, the client can learn about the the request content. This way, the client can learn about the
resource's support for resumable uploads and/or the upload resource's resource's support for resumable uploads and/or the upload resource's
URI. This is conceptually similar to how a client might wait for a URI. This is conceptually similar to how a client might wait for a
100 (Continue) interim response (see Section 10.1.1 of [HTTP]) before 100 (Continue) interim response (see Section 10.1.1 of [HTTP]) before
committing to work. committing to work.
12.1.1. Upgrading To Resumable Uploads 12.1.1. Upgrading To Resumable Uploads
skipping to change at page 33, line 38 skipping to change at page 34, line 5
Optimistic upload creation allows clients and servers to Optimistic upload creation allows clients and servers to
automatically upgrade non-resumable uploads to resumable ones. In a automatically upgrade non-resumable uploads to resumable ones. In a
non-resumable upload, the representation is transferred in a single non-resumable upload, the representation is transferred in a single
request, usually "POST" or "PUT", without any ability to resume from request, usually "POST" or "PUT", without any ability to resume from
interruptions. The client can invite the server to upgrade such a interruptions. The client can invite the server to upgrade such a
request to a resumable upload by adding the "Upload-Complete: ?1" request to a resumable upload by adding the "Upload-Complete: ?1"
header field to the original request. The "Upload-Length" header header field to the original request. The "Upload-Length" header
field SHOULD be added if the representation data's length is known field SHOULD be added if the representation data's length is known
upfront. The request is not changed otherwise. upfront. The request is not changed otherwise.
A server that supports resumable uploads at the target URI can create If the resource targeted in the initial request supports resumable
an upload resource and send its URI in a "104 (Upload Resumption uploads, the server can create an upload resource and send its URI in
Supported)" interim response for the client to resume the upload a "104 (Upload Resumption Supported)" interim response for the client
after interruptions. A server that does not support resumable to resume the upload after interruptions. A resource that does not
uploads or does not want to upgrade to a resumable upload for this support resumable uploads or does not want to upgrade to a resumable
request ignores the "Upload-Complete: ?1" header. The transfer then upload for this request ignores the "Upload-Complete: ?1" header.
falls back to a non-resumable upload without additional cost. The transfer then falls back to a non-resumable upload without
additional cost.
This upgrade can also be performed transparently by a library or This upgrade can also be performed transparently by a library or
program that acts as a HTTP client by sending requests on behalf of a program that acts as a HTTP client by sending requests on behalf of a
user. When the user instructs the client to send a non-resumable user. When the user instructs the client to send a non-resumable
request, the client can perform the upgrade transparently and handle request, the client can perform the upgrade transparently and handle
potential interruptions and resumptions under the hood without potential interruptions and resumptions under the hood without
involving the user. The last response received by the client is involving the user. The last response received by the client is
considered the response for the entire upload and should be provided considered the response for the entire upload and should be provided
to the user. to the user.
12.2. Careful Upload Creation 12.2. Careful Upload Creation
For a "careful upload creation" the client knows that the server For a "careful upload creation" the client knows that the resource
supports resumable uploads and sends an empty upload creation request targeted in the initial request supports resumable uploads and sends
without including any representation data. Upon successful response an empty upload creation request without including any representation
reception, the client can use the included upload resource URI to data. Upon successful response reception, the client can use the
transmit the representation data (Section 4.4) and resume the upload included upload resource URI to transmit the representation data
at any stage if an interruption occurs. The client should inspect (Section 4.4) and resume the upload at any stage if an interruption
the response for the "Upload-Limit" header field, which would occurs. The client should inspect the response for the "Upload-
indicate limits applying to the remaining upload procedure. Limit" header field, which would indicate limits applying to the
remaining upload procedure.
The retransmission of representation data or the ultimate upload The retransmission of representation data or the ultimate upload
failure that can happen with an "optimistic upload creation" is failure that can happen with an "optimistic upload creation" is
therefore avoided at the expense of an additional request that does therefore avoided at the expense of an additional request that does
not carry representation data. not carry representation data.
This approach is best suited if the client cannot receive interim This approach is best suited if the client cannot receive interim
responses, e.g. due to a limitation in the provided HTTP interface, responses, e.g. due to a limitation in the provided HTTP interface,
or if large representations are transferred where the cost of the or if large representations are transferred where the cost of the
additional request is minuscule compared to the effort of additional request is minuscule compared to the effort of
skipping to change at page 39, line 48 skipping to change at page 40, line 19
http://ha.ckers.org/slowloris/>. http://ha.ckers.org/slowloris/>.
15.3. URIs 15.3. URIs
[1] https://tus.io/ [1] https://tus.io/
Appendix A. Changes Appendix A. Changes
This section is to be removed before publishing as an RFC. This section is to be removed before publishing as an RFC.
A.1. Since draft-ietf-httpbis-resumable-upload-10 A.1. Since draft-ietf-httpbis-resumable-upload-11
o Clear up different responsibilities of server and upload resource.
o Relax recommendations on client handling greater offsets.
o Clarify client behavior for 413 responses.
A.2. Since draft-ietf-httpbis-resumable-upload-10
o Add recommended disposition type for file name indication. o Add recommended disposition type for file name indication.
A.2. Since draft-ietf-httpbis-resumable-upload-09 A.3. Since draft-ietf-httpbis-resumable-upload-09
o Requires Accept-Patch in OPTIONS. o Requires Accept-Patch in OPTIONS.
o Add security consideration regarding time-of-check to time-of-use. o Add security consideration regarding time-of-check to time-of-use.
o Lift requirement on Upload-Complete for all final responses. o Lift requirement on Upload-Complete for all final responses.
o Relax requirements on limit changes. o Relax requirements on limit changes.
o Describe the interaction between 100 and 104 responses. o Describe the interaction between 100 and 104 responses.
o Numerous editorial improvements. o Numerous editorial improvements.
A.3. Since draft-ietf-httpbis-resumable-upload-08 A.4. Since draft-ietf-httpbis-resumable-upload-08
o Clarify definitions of new header fields. o Clarify definitions of new header fields.
o Make handling of OPTIONS * optional. o Make handling of OPTIONS * optional.
o Require server to announce limits using Upload-Limit. o Require server to announce limits using Upload-Limit.
o Require clients to adhere to known limits. o Require clients to adhere to known limits.
o Rephrase requirements for concurrency handling, focusing on the o Rephrase requirements for concurrency handling, focusing on the
outcome. outcome.
o Remove requirement for 204 status code for DELETE responses. o Remove requirement for 204 status code for DELETE responses.
o Increase the draft interop version. o Increase the draft interop version.
o Add section about 104 status code. o Add section about 104 status code.
o Rephrase recommendation for sending information back to client. o Rephrase recommendation for sending information back to client.
A.4. Since draft-ietf-httpbis-resumable-upload-07 A.5. Since draft-ietf-httpbis-resumable-upload-07
o Clarify server handling when upload length is exceeded. o Clarify server handling when upload length is exceeded.
o Extend security considerations about upload resource URIs, o Extend security considerations about upload resource URIs,
representation metadata, and untrusted inputs. representation metadata, and untrusted inputs.
o Allow clients to retry for appropriate 4xx responses. o Allow clients to retry for appropriate 4xx responses.
A.5. Since draft-ietf-httpbis-resumable-upload-06 A.6. Since draft-ietf-httpbis-resumable-upload-06
o Minor editorial improvements to introduction and examples. o Minor editorial improvements to introduction and examples.
o Define structured types for new header fields. o Define structured types for new header fields.
A.6. Since draft-ietf-httpbis-resumable-upload-05 A.7. Since draft-ietf-httpbis-resumable-upload-05
o Increase the draft interop version. o Increase the draft interop version.
o Numerous editorial changes. o Numerous editorial changes.
o Rename "expires" limit to "max-age". o Rename "expires" limit to "max-age".
o Require "Upload-Complete", but not "Upload-Offset" or "Upload- o Require "Upload-Complete", but not "Upload-Offset" or "Upload-
Limit", for append responses. Limit", for append responses.
o Add problem type for inconsistent length values. o Add problem type for inconsistent length values.
o Reduce use of "file" in favor of "representation". o Reduce use of "file" in favor of "representation".
A.7. Since draft-ietf-httpbis-resumable-upload-04 A.8. Since draft-ietf-httpbis-resumable-upload-04
o Clarify implications of "Upload-Limit" header. o Clarify implications of "Upload-Limit" header.
o Allow client to fetch upload limits upfront via "OPTIONS". o Allow client to fetch upload limits upfront via "OPTIONS".
o Add guidance on upload creation strategy. o Add guidance on upload creation strategy.
o Add "Upload-Length" header to indicate length during creation. o Add "Upload-Length" header to indicate length during creation.
o Describe possible usage of "Want-Repr-Digest". o Describe possible usage of "Want-Repr-Digest".
A.8. Since draft-ietf-httpbis-resumable-upload-03 A.9. Since draft-ietf-httpbis-resumable-upload-03
o Add note about "Content-Location" for referring to subsequent o Add note about "Content-Location" for referring to subsequent
resources. resources.
o Require "application/partial-upload" for appending to uploads. o Require "application/partial-upload" for appending to uploads.
o Explain handling of content and transfer codings. o Explain handling of content and transfer codings.
o Add problem types for mismatching offsets and completed uploads. o Add problem types for mismatching offsets and completed uploads.
o Clarify that completed uploads must not be appended to. o Clarify that completed uploads must not be appended to.
o Describe interaction with Digest Fields from RFC9530. o Describe interaction with Digest Fields from RFC9530.
o Require that upload offset does not decrease over time. o Require that upload offset does not decrease over time.
o Add Upload-Limit header field. o Add Upload-Limit header field.
o Increase the draft interop version. o Increase the draft interop version.
A.9. Since draft-ietf-httpbis-resumable-upload-02 A.10. Since draft-ietf-httpbis-resumable-upload-02
o Add upload progress notifications via informational responses. o Add upload progress notifications via informational responses.
o Add security consideration regarding request filtering. o Add security consideration regarding request filtering.
o Explain the use of empty requests for creation uploads and o Explain the use of empty requests for creation uploads and
appending. appending.
o Extend security consideration to include resource exhaustion o Extend security consideration to include resource exhaustion
attacks. attacks.
o Allow 200 status codes for offset retrieval. o Allow 200 status codes for offset retrieval.
o Increase the draft interop version. o Increase the draft interop version.
A.10. Since draft-ietf-httpbis-resumable-upload-01 A.11. Since draft-ietf-httpbis-resumable-upload-01
o Replace Upload-Incomplete header with Upload-Complete. o Replace Upload-Incomplete header with Upload-Complete.
o Replace terminology about procedures with HTTP resources. o Replace terminology about procedures with HTTP resources.
o Increase the draft interop version. o Increase the draft interop version.
A.11. Since draft-ietf-httpbis-resumable-upload-00 A.12. Since draft-ietf-httpbis-resumable-upload-00
o Remove Upload-Token and instead use Server-generated upload URL o Remove Upload-Token and instead use Server-generated upload URL
for upload identification. for upload identification.
o Require the Upload-Incomplete header field in Upload Creation o Require the Upload-Incomplete header field in Upload Creation
Procedure. Procedure.
o Increase the draft interop version. o Increase the draft interop version.
A.12. Since draft-tus-httpbis-resumable-uploads-protocol-02 A.13. Since draft-tus-httpbis-resumable-uploads-protocol-02
None None
A.13. Since draft-tus-httpbis-resumable-uploads-protocol-01 A.14. Since draft-tus-httpbis-resumable-uploads-protocol-01
o Clarifying backtracking and preventing skipping ahead during the o Clarifying backtracking and preventing skipping ahead during the
Offset Receiving Procedure. Offset Receiving Procedure.
o Clients auto-retry 404 is no longer allowed. o Clients auto-retry 404 is no longer allowed.
A.14. Since draft-tus-httpbis-resumable-uploads-protocol-00 A.15. Since draft-tus-httpbis-resumable-uploads-protocol-00
o Split the Upload Transfer Procedure into the Upload Creation o Split the Upload Transfer Procedure into the Upload Creation
Procedure and the Upload Appending Procedure. Procedure and the Upload Appending Procedure.
Appendix B. Draft Version Identification Appendix B. Draft Version Identification
This section is to be removed before publishing as an RFC. This section is to be removed before publishing as an RFC.
To assist the development of implementations and interoperability To assist the development of implementations and interoperability
testing while this document is still a draft, an interop version is testing while this document is still a draft, an interop version is
 End of changes. 103 change blocks. 
296 lines changed or deleted 321 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/