draft-ietf-httpbis-resumable-upload-09.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: December 6, 2025 Apple Inc. | Expires: March 6, 2026 Apple Inc. | |||
L. Pardue, Ed. | L. Pardue, Ed. | |||
Cloudflare | Cloudflare | |||
June 04, 2025 | September 02, 2025 | |||
Resumable Uploads for HTTP | Resumable Uploads for HTTP | |||
draft-ietf-httpbis-resumable-upload-09 | draft-ietf-httpbis-resumable-upload-latest | |||
Abstract | Abstract | |||
Data transfer using the Hypertext Transfer Protocol (HTTP) is often | HTTP data transfers can encounter interruption due to reasons such as | |||
interrupted by canceled requests or dropped connections. If the | canceled requests or dropped connections. If the intended recipient | |||
intended recipient can indicate how much of the data was received | can indicate how much of the data was received prior to interruption, | |||
prior to interruption, a sender can resume data transfer at that | a sender can resume data transfer at that point instead of attempting | |||
point instead of attempting to transfer all of the data again. HTTP | to transfer all of the data again. HTTP range requests support this | |||
range requests support this concept of resumable downloads from | concept of resumable downloads from server to client. This document | |||
server to client. This document describes a mechanism that supports | describes a mechanism that supports resumable uploads from client to | |||
resumable uploads from client to server using HTTP. | 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 December 6, 2025. | This Internet-Draft will expire on March 6, 2026. | |||
Copyright Notice | Copyright Notice | |||
Copyright (c) 2025 IETF Trust and the persons identified as the | Copyright (c) 2025 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 | |||
carefully, as they describe your rights and restrictions with respect | carefully, as they describe your rights and restrictions with respect | |||
to this document. Code Components extracted from this document must | to this document. Code Components extracted from this document must | |||
include Simplified BSD License text as described in Section 4.e of | include Simplified BSD License text as described in Section 4.e of | |||
the Trust Legal Provisions and are provided without warranty as | the Trust Legal Provisions and are provided without warranty as | |||
described in the Simplified BSD License. | described in the Simplified BSD License. | |||
Table of Contents | Table of Contents | |||
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 | 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 | |||
2. Conventions and Definitions . . . . . . . . . . . . . . . . . 4 | 2. Conventions and Definitions . . . . . . . . . . . . . . . . . 5 | |||
3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 5 | 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 5 | |||
3.1. Example 1: Complete upload of representation data with | 3.1. Example 1: Complete upload of representation data with | |||
known size . . . . . . . . . . . . . . . . . . . . . . . 5 | known size . . . . . . . . . . . . . . . . . . . . . . . 6 | |||
3.2. Example 2: Upload as a series of parts . . . . . . . . . 7 | 3.2. Example 2: Upload as a series of parts . . . . . . . . . 8 | |||
4. Upload Resource . . . . . . . . . . . . . . . . . . . . . . . 9 | 4. Upload Resource . . . . . . . . . . . . . . . . . . . . . . . 10 | |||
4.1. State . . . . . . . . . . . . . . . . . . . . . . . . . . 10 | 4.1. State . . . . . . . . . . . . . . . . . . . . . . . . . . 10 | |||
4.1.1. Offset . . . . . . . . . . . . . . . . . . . . . . . 10 | 4.1.1. Offset . . . . . . . . . . . . . . . . . . . . . . . 11 | |||
4.1.2. Completeness . . . . . . . . . . . . . . . . . . . . 11 | 4.1.2. Completeness . . . . . . . . . . . . . . . . . . . . 11 | |||
4.1.3. Length . . . . . . . . . . . . . . . . . . . . . . . 11 | 4.1.3. Length . . . . . . . . . . . . . . . . . . . . . . . 12 | |||
4.1.4. Limits . . . . . . . . . . . . . . . . . . . . . . . 12 | 4.1.4. Limits . . . . . . . . . . . . . . . . . . . . . . . 12 | |||
4.2. Upload Creation . . . . . . . . . . . . . . . . . . . . . 14 | 4.2. Upload Creation . . . . . . . . . . . . . . . . . . . . . 14 | |||
4.2.1. Client Behavior . . . . . . . . . . . . . . . . . . . 14 | 4.2.1. Client Behavior . . . . . . . . . . . . . . . . . . . 15 | |||
4.2.2. Server Behavior . . . . . . . . . . . . . . . . . . . 15 | 4.2.2. Server Behavior . . . . . . . . . . . . . . . . . . . 16 | |||
4.2.3. Examples . . . . . . . . . . . . . . . . . . . . . . 16 | 4.2.3. Examples . . . . . . . . . . . . . . . . . . . . . . 17 | |||
4.3. Offset Retrieval . . . . . . . . . . . . . . . . . . . . 18 | 4.3. Offset Retrieval . . . . . . . . . . . . . . . . . . . . 19 | |||
4.3.1. Client Behavior . . . . . . . . . . . . . . . . . . . 18 | 4.3.1. Client Behavior . . . . . . . . . . . . . . . . . . . 19 | |||
4.3.2. Server Behavior . . . . . . . . . . . . . . . . . . . 19 | 4.3.2. Server Behavior . . . . . . . . . . . . . . . . . . . 20 | |||
4.3.3. Example . . . . . . . . . . . . . . . . . . . . . . . 19 | 4.3.3. Examples . . . . . . . . . . . . . . . . . . . . . . 20 | |||
4.4. Upload Append . . . . . . . . . . . . . . . . . . . . . . 20 | 4.4. Upload Append . . . . . . . . . . . . . . . . . . . . . . 21 | |||
4.4.1. Client Behavior . . . . . . . . . . . . . . . . . . . 20 | 4.4.1. Client Behavior . . . . . . . . . . . . . . . . . . . 21 | |||
4.4.2. Server Behavior . . . . . . . . . . . . . . . . . . . 21 | 4.4.2. Server Behavior . . . . . . . . . . . . . . . . . . . 22 | |||
4.4.3. Example . . . . . . . . . . . . . . . . . . . . . . . 22 | 4.4.3. Examples . . . . . . . . . . . . . . . . . . . . . . 23 | |||
4.5. Upload Cancellation . . . . . . . . . . . . . . . . . . . 23 | 4.5. Upload Cancellation . . . . . . . . . . . . . . . . . . . 24 | |||
4.5.1. Client Behavior . . . . . . . . . . . . . . . . . . . 23 | 4.5.1. Client Behavior . . . . . . . . . . . . . . . . . . . 24 | |||
4.5.2. Server Behavior . . . . . . . . . . . . . . . . . . . 23 | 4.5.2. Server Behavior . . . . . . . . . . . . . . . . . . . 24 | |||
4.5.3. Example . . . . . . . . . . . . . . . . . . . . . . . 24 | 4.5.3. Example . . . . . . . . . . . . . . . . . . . . . . . 25 | |||
4.6. Concurrency . . . . . . . . . . . . . . . . . . . . . . . 24 | 4.6. Concurrency . . . . . . . . . . . . . . . . . . . . . . . 25 | |||
5. Status Code 104 (Upload Resumption Supported) . . . . . . . . 25 | 5. Status Code 104 (Upload Resumption Supported) . . . . . . . . 26 | |||
6. Media Type application/partial-upload . . . . . . . . . . . . 25 | 6. Media Type application/partial-upload . . . . . . . . . . . . 26 | |||
7. Problem Types . . . . . . . . . . . . . . . . . . . . . . . . 26 | 7. Problem Types . . . . . . . . . . . . . . . . . . . . . . . . 27 | |||
7.1. Mismatching Offset . . . . . . . . . . . . . . . . . . . 26 | 7.1. Mismatching Offset . . . . . . . . . . . . . . . . . . . 27 | |||
7.2. Completed Upload . . . . . . . . . . . . . . . . . . . . 26 | 7.2. Completed Upload . . . . . . . . . . . . . . . . . . . . 27 | |||
7.3. Inconsistent Length . . . . . . . . . . . . . . . . . . . 27 | 7.3. Inconsistent Length . . . . . . . . . . . . . . . . . . . 28 | |||
8. Content Codings . . . . . . . . . . . . . . . . . . . . . . . 27 | 8. Content Codings . . . . . . . . . . . . . . . . . . . . . . . 28 | |||
9. Transfer Codings . . . . . . . . . . . . . . . . . . . . . . 28 | 9. Transfer Codings . . . . . . . . . . . . . . . . . . . . . . 29 | |||
10. Integrity Digests . . . . . . . . . . . . . . . . . . . . . . 28 | 10. Integrity Digests . . . . . . . . . . . . . . . . . . . . . . 29 | |||
10.1. Representation Digests . . . . . . . . . . . . . . . . . 28 | 10.1. Representation Digests . . . . . . . . . . . . . . . . . 29 | |||
10.2. Content Digests . . . . . . . . . . . . . . . . . . . . 29 | 10.2. Content Digests . . . . . . . . . . . . . . . . . . . . 30 | |||
11. Responses to Uploads . . . . . . . . . . . . . . . . . . . . 29 | 11. Responses to Uploads . . . . . . . . . . . . . . . . . . . . 30 | |||
12. Upload Strategies . . . . . . . . . . . . . . . . . . . . . . 30 | 12. Upload Strategies . . . . . . . . . . . . . . . . . . . . . . 31 | |||
12.1. Optimistic Upload Creation . . . . . . . . . . . . . . . 30 | 12.1. Optimistic Upload Creation . . . . . . . . . . . . . . . 31 | |||
12.1.1. Upgrading To Resumable Uploads . . . . . . . . . . . 31 | 12.1.1. Upgrading To Resumable Uploads . . . . . . . . . . . 32 | |||
12.2. Careful Upload Creation . . . . . . . . . . . . . . . . 31 | 12.2. Careful Upload Creation . . . . . . . . . . . . . . . . 32 | |||
13. Security Considerations . . . . . . . . . . . . . . . . . . . 32 | 13. Security Considerations . . . . . . . . . . . . . . . . . . . 33 | |||
14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 33 | 14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 34 | |||
14.1. HTTP Fields . . . . . . . . . . . . . . . . . . . . . . 33 | 14.1. HTTP Fields . . . . . . . . . . . . . . . . . . . . . . 34 | |||
14.2. HTTP Status Code . . . . . . . . . . . . . . . . . . . . 33 | 14.2. HTTP Status Code . . . . . . . . . . . . . . . . . . . . 34 | |||
14.3. Media Type . . . . . . . . . . . . . . . . . . . . . . . 33 | 14.3. Media Type . . . . . . . . . . . . . . . . . . . . . . . 35 | |||
14.4. HTTP Problem Types . . . . . . . . . . . . . . . . . . . 34 | 14.4. HTTP Problem Types . . . . . . . . . . . . . . . . . . . 36 | |||
15. References . . . . . . . . . . . . . . . . . . . . . . . . . 35 | 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 36 | |||
15.1. Normative References . . . . . . . . . . . . . . . . . . 35 | 15.1. Normative References . . . . . . . . . . . . . . . . . . 36 | |||
15.2. Informative References . . . . . . . . . . . . . . . . . 36 | 15.2. Informative References . . . . . . . . . . . . . . . . . 37 | |||
Appendix A. Changes . . . . . . . . . . . . . . . . . . . . . . 37 | Appendix A. Changes . . . . . . . . . . . . . . . . . . . . . . 38 | |||
A.1. Since draft-ietf-httpbis-resumable-upload-08 . . . . . . 37 | A.1. Since draft-ietf-httpbis-resumable-upload-09 . . . . . . 38 | |||
A.2. Since draft-ietf-httpbis-resumable-upload-07 . . . . . . 37 | A.2. Since draft-ietf-httpbis-resumable-upload-08 . . . . . . 38 | |||
A.3. Since draft-ietf-httpbis-resumable-upload-06 . . . . . . 37 | A.3. Since draft-ietf-httpbis-resumable-upload-07 . . . . . . 38 | |||
A.4. Since draft-ietf-httpbis-resumable-upload-05 . . . . . . 38 | A.4. Since draft-ietf-httpbis-resumable-upload-06 . . . . . . 39 | |||
A.5. Since draft-ietf-httpbis-resumable-upload-04 . . . . . . 38 | A.5. Since draft-ietf-httpbis-resumable-upload-05 . . . . . . 39 | |||
A.6. Since draft-ietf-httpbis-resumable-upload-03 . . . . . . 38 | A.6. Since draft-ietf-httpbis-resumable-upload-04 . . . . . . 39 | |||
A.7. Since draft-ietf-httpbis-resumable-upload-02 . . . . . . 39 | A.7. Since draft-ietf-httpbis-resumable-upload-03 . . . . . . 39 | |||
A.8. Since draft-ietf-httpbis-resumable-upload-01 . . . . . . 39 | A.8. Since draft-ietf-httpbis-resumable-upload-02 . . . . . . 40 | |||
A.9. Since draft-ietf-httpbis-resumable-upload-00 . . . . . . 39 | A.9. Since draft-ietf-httpbis-resumable-upload-01 . . . . . . 40 | |||
A.10. Since draft-tus-httpbis-resumable-uploads-protocol-02 . . 39 | A.10. Since draft-ietf-httpbis-resumable-upload-00 . . . . . . 40 | |||
A.11. Since draft-tus-httpbis-resumable-uploads-protocol-01 . . 39 | A.11. Since draft-tus-httpbis-resumable-uploads-protocol-02 . . 40 | |||
A.12. Since draft-tus-httpbis-resumable-uploads-protocol-00 . . 40 | A.12. Since draft-tus-httpbis-resumable-uploads-protocol-01 . . 41 | |||
Appendix B. Draft Version Identification . . . . . . . . . . . . 40 | A.13. Since draft-tus-httpbis-resumable-uploads-protocol-00 . . 41 | |||
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 40 | Appendix B. Draft Version Identification . . . . . . . . . . . . 41 | |||
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 41 | Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 42 | |||
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 42 | ||||
1. Introduction | 1. Introduction | |||
Data transfer using the Hypertext Transfer Protocol ([HTTP]) is often | HTTP data transfers can encounter interruption due to reasons such as | |||
interrupted by canceled requests or dropped connections. If the | canceled requests or dropped connections. If the intended recipient | |||
intended recipient can indicate how much of the data was received | can indicate how much of the data was received prior to interruption, | |||
prior to interruption, a sender can resume data transfer at that | a sender can resume data transfer at that point instead of attempting | |||
point instead of attempting to transfer all of the data again. HTTP | to transfer all of the data again. HTTP range requests (see | |||
range requests (see Section 14 of [HTTP]) support this concept of | Section 14 of [HTTP]) support this concept of resumable data | |||
resumable data transfers for downloads from server to client. | transfers for downloads from server to client. While partial PUT is | |||
one method for uploading a partial representation (via Content-Range | ||||
in the request), there are caveats that affect its deployability; see | ||||
Section 14.5 of [HTTP]. | ||||
This specification defines a mechanism for resumable uploads from | Canceled upload request can be triggered for various reasons, | |||
including but not limited to: | ||||
explicit client cancellation: e.g., terminating a user-agent process | ||||
implicit client cancellation: e.g., terminating a tab, garbage | ||||
collecting a process or internal error | ||||
explicit server cancellation: e.g., scheduled maintenance | ||||
implicit server cancellation: e.g., DoS mitigation or internal error | ||||
Connections can be dropped due to a variety of network or transport | ||||
layer reasons triggered by endpoints or on-path elements. | ||||
This specification defines a new mechanism for resumable uploads from | ||||
client to server in a way that is backwards-compatible with | client to server in a way that is backwards-compatible with | |||
conventional HTTP uploads. When an upload is interrupted, clients | conventional HTTP uploads. When an upload is interrupted, clients | |||
can send subsequent requests to query the server state and use this | can send subsequent requests to query the server state and use this | |||
information to send the remaining representation data. | information to send the remaining representation data. | |||
Alternatively, they can cancel the upload entirely. Unlike ranged | Alternatively, they can cancel the upload entirely. Unlike ranged | |||
downloads, this protocol does not support transferring an upload as | downloads, this protocol does not support transferring an upload as | |||
multiple requests in parallel. | multiple requests in parallel. | |||
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 | |||
skipping to change at page 5, line 30 ¶ | skipping to change at page 5, line 46 ¶ | |||
resource being uploaded to and specific to that upload. By | resource being uploaded to and specific to that upload. By | |||
interacting with the upload resource, a client can retrieve the | interacting with the upload resource, a client can retrieve the | |||
current offset of the upload (Section 4.3), append to the upload | current offset of the upload (Section 4.3), append to the upload | |||
(Section 4.4), and cancel the upload (Section 4.5). | (Section 4.4), and cancel the upload (Section 4.5). | |||
The remainder of this section uses examples to illustrate different | The remainder of this section uses examples to illustrate different | |||
interactions with the upload resource. HTTP message exchanges, and | interactions with the upload resource. HTTP message exchanges, and | |||
thereby resumable uploads, use representation data (see Section 8.1 | thereby resumable uploads, use representation data (see Section 8.1 | |||
of [HTTP]). This means that resumable uploads can be used with many | of [HTTP]). This means that resumable uploads can be used with many | |||
forms of content, such as static files, in-memory buffers, data from | forms of content, such as static files, in-memory buffers, data from | |||
streaming sources, or on-demand generated data. | streaming sources, or on-demand generated data. Examples are purely | |||
illustrative and non-normative. Implementations of this protocol are | ||||
expected to follow normative requirements defined in other sections, | ||||
together with applying security considerations presented in | ||||
Section 13. | ||||
3.1. Example 1: Complete upload of representation data with known size | 3.1. Example 1: Complete upload of representation data with known size | |||
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 | |||
skipping to change at page 8, line 18 ¶ | skipping to change at page 8, line 46 ¶ | |||
| Upload-Complete: ?0 | | | Upload-Complete: ?0 | | |||
|------------------------------------------------>| | |------------------------------------------------>| | |||
| | | | | | |||
| 201 Created | | | 201 Created | | |||
| Location: /uploads/abc | | | Location: /uploads/abc | | |||
|<------------------------------------------------| | |<------------------------------------------------| | |||
| | | | | | |||
Figure 5: Upload creation with partial representation data | Figure 5: Upload creation with partial representation data | |||
2) Subsequent, intermediate parts are appended (Section 4.4) with the | 2) Subsequently, intermediate parts are appended (Section 4.4) with | |||
"Upload-Complete" field value set to false, indicating that they are | the "Upload-Complete" field value set to false, indicating that they | |||
not the last part of the representation data. The offset value in | are not the last part of the representation data. The offset value | |||
the "Upload-Offset" header field is taken from the previous response | in the "Upload-Offset" header field is taken from the previous | |||
when creating the upload or appending to it. | response when creating the upload or appending to it. | |||
Client Server | Client Server | |||
| | | | | | |||
| PATCH /uploads/abc | | | PATCH /uploads/abc | | |||
| Upload-Complete: ?0 | | | Upload-Complete: ?0 | | |||
| Upload-Offset: X | | | Upload-Offset: X | | |||
| Content-Type: application/partial-upload | | | Content-Type: application/partial-upload | | |||
|------------------------------------------------>| | |------------------------------------------------>| | |||
| | | | | | |||
| 204 No Content | | | 204 No Content | | |||
skipping to change at page 13, line 45 ¶ | skipping to change at page 14, line 20 ¶ | |||
request sent to this target URI. If a server supports the creation | request sent to this target URI. If a server supports the creation | |||
of upload resources for any target URI, it SHOULD include the | of upload resources for any target URI, it SHOULD include the | |||
"Upload-Limit" header field with the corresponding limits in a | "Upload-Limit" header field with the corresponding limits in a | |||
response to an "OPTIONS" request with the "*" target unless the | response to an "OPTIONS" request with the "*" target unless the | |||
server is not capable of handling "OPTIONS *" requests. If the | server is not capable of handling "OPTIONS *" requests. If the | |||
server does not apply any limits, it MUST use "min-size=0" instead of | server does not apply any limits, it MUST use "min-size=0" instead of | |||
an empty header value. | an empty header value. | |||
A client can use an "OPTIONS" request to discover support for | A client can use an "OPTIONS" request to discover support for | |||
resumable uploads and potential limits before creating an upload | resumable uploads and potential limits before creating an upload | |||
resource. To reduce the liklihood of failing requests, the limits | resource. To reduce the likelihood of failing requests, the limits | |||
announced in an "OPTIONS" response SHOULD NOT be less restrictive | announced in an "OPTIONS" response SHOULD NOT be less restrictive | |||
than the limits applied to an upload once the upload resource has | than the limits applied to an upload once the upload resource has | |||
been created, unless the request to create an upload resource | been created, unless the request to create an upload resource | |||
included additional information that warrants different limits. For | included additional information that warrants different limits. For | |||
example, a server might announce a general maximum size limit of 1GB, | example, a server might announce a general maximum size limit of 1GB, | |||
but reduce it to 100MB when the media type indicates an image. | but reduce it to 100MB when the media type indicates an image. | |||
4.2. Upload Creation | Servers, including intermediaries, can (and often do) apply | |||
restrictions on the size of individual request message content. | ||||
There is no standard mechanism to communicate such existing size | ||||
restriction. A server that implements one can respond with a 413 | ||||
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 | ||||
to upload data up to the "max-size" limit without encountering per- | ||||
message limits. The "min-append-size" and "max-append-size" limits | ||||
apply to the upload resource. Servers might apply restrictions that | ||||
are smaller than the append limits, which would also result in a | ||||
failed request. Clients could deal with such situations by retrying | ||||
an upload append using a smaller size, as long as the new size | ||||
resides between "min-append-size" and "max-append-size". Cases where | ||||
an append uses "min-append-size" yet fails with a 413 Content Too | ||||
Large response might indicate a deployment mismatch that cannot be | ||||
recovered from. | ||||
Uploading as a series of parts | ||||
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". | |||
The "Upload-Complete" header field is set to true if the request | The "Upload-Complete" header field is set to true if the request | |||
content includes the entire representation data that the client | content includes the entire representation data that the client | |||
intends to upload. This is also a requirement for transparently | intends to upload. This is also a requirement for transparently | |||
skipping to change at page 14, line 35 ¶ | skipping to change at page 15, line 32 ¶ | |||
The client SHOULD respect any limits (Section 4.1.4) announced in the | The client SHOULD respect any limits (Section 4.1.4) announced in the | |||
"Upload-Limit" header field in interim or final responses. In | "Upload-Limit" header field in interim or final responses. In | |||
particular, if the allowed maximum size is less than the amount of | particular, if the allowed maximum size is less than the amount of | |||
representation data the client intends to upload, the client SHOULD | representation data the client intends to upload, the client SHOULD | |||
stop the current request immediately and cancel the upload | stop the current request immediately and cancel the upload | |||
(Section 4.5). | (Section 4.5). | |||
The request content can be empty. If the "Upload-Complete" header | The request content can be empty. If the "Upload-Complete" header | |||
field is then set to true, the client intends to upload an empty | field is then set to true, the client intends to upload an empty | |||
representation. An "Upload-Complete" header field is set to false is | representation. An "Upload-Complete" header field set to false is | |||
also valid. This can be used to retrieve the upload resource's URI | also valid. This can be used to retrieve the upload resource's URI | |||
before transferring any representation data. Since interim responses | before transferring any representation data. Since interim responses | |||
are optional, this technique provides another mechanism to learn the | are optional, this technique provides another mechanism to learn the | |||
URI, at the cost of an additional round-trip before data upload can | URI, at the cost of an additional round-trip before data upload can | |||
commence. | commence. | |||
Representation metadata included in the initial request (see | Representation metadata included in the initial request (see | |||
Section 8.3 of [HTTP]) can affect how servers act on the uploaded | Section 8.3 of [HTTP]) can affect how servers act on the uploaded | |||
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 | |||
skipping to change at page 15, line 4 ¶ | skipping to change at page 15, line 49 ¶ | |||
Representation metadata included in the initial request (see | Representation metadata included in the initial request (see | |||
Section 8.3 of [HTTP]) can affect how servers act on the uploaded | Section 8.3 of [HTTP]) can affect how servers act on the uploaded | |||
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-Disposition" header field ([CONTENT-DISPOSITION]) can be | "Content-Disposition" header field ([CONTENT-DISPOSITION]) can be | |||
used to transmit a filename. The "Content-Encoding" header field | used to transmit a filename. The "Content-Encoding" header field | |||
(Section 8.4 of [HTTP]) names the content codings applied to the | (Section 8.4 of [HTTP]) names the content codings applied to the | |||
representation. | representation. | |||
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 entire representation data | |||
was transferred in the request content, the upload is complete and | was transferred in the request content, the upload is complete and | |||
the response belongs to the targeted resource processing the | the response belongs to the targeted resource processing the | |||
representation. | representation. | |||
o "2xx (Successful)" status code and not the entire representation | o "2xx (Successful)" status code and the entire representation data | |||
data was transferred in the request content, the "Location" | was not transferred in the request content, the "Location" | |||
response header field points the client to the created upload | response header field points the client to the created upload | |||
resource. The client can continue appending representation data | resource. The client can continue appending representation data | |||
to it (Section 4.4). | to it (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 | |||
skipping to change at page 16, line 27 ¶ | skipping to change at page 17, line 25 ¶ | |||
If the server does not receive the entire request content, for | If the server does not receive the entire request content, for | |||
example because of canceled requests or dropped connections, it | example because of canceled requests or dropped connections, it | |||
SHOULD append as much of the request content as possible to the | SHOULD append as much of the request content as possible to the | |||
upload resource. The upload resource MUST NOT be considered complete | upload resource. The upload resource MUST NOT be considered complete | |||
then. | 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 | |||
100 bytes are transferred in the initial request. The server sends | 100000000 bytes are transferred in the initial request. The server | |||
multiple interim responses and one final response from processing the | sends multiple interim responses and one final response from | |||
uploaded representation. | processing the uploaded representation. | |||
POST /project/123/files HTTP/1.1 | POST /project/123/files HTTP/1.1 | |||
Host: example.com | Host: example.com | |||
Upload-Complete: ?1 | Upload-Complete: ?1 | |||
Content-Length: 100 | Content-Length: 100000000 | |||
Upload-Length: 100 | Upload-Length: 100000000 | |||
[content (100 bytes)] | [content (100000000 bytes)] | |||
HTTP/1.1 104 Upload Resumption Supported | HTTP/1.1 104 Upload Resumption Supported | |||
Location: https://example.com/upload/b530ce8ff | Location: https://example.com/upload/b530ce8ff | |||
Upload-Limit: max-size=1000000000 | Upload-Limit: max-size=1000000000 | |||
HTTP/1.1 104 Upload Resumption Supported | HTTP/1.1 104 Upload Resumption Supported | |||
Upload-Offset: 50 | Upload-Offset: 50000000 | |||
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=1000000000 | Upload-Limit: max-size=1000000000 | |||
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 25 bytes of a 100 bytes upload are transferred. The server | first 25000000 bytes of a 100000000 bytes upload are transferred. | |||
acknowledges the received representation data and that the upload is | The server acknowledges the received representation data and that the | |||
not complete yet. The client can continue appending data. | 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: 25 | Content-Length: 25000000 | |||
Upload-Length: 100 | Upload-Length: 100000000 | |||
[partial content (25 bytes)] | [partial content (25000000 bytes)] | |||
HTTP/1.1 104 Upload Resumption Supported | HTTP/1.1 104 Upload Resumption Supported | |||
Location: https://example.com/upload/b530ce8ff | Location: https://example.com/upload/b530ce8ff | |||
HTTP/1.1 201 Created | HTTP/1.1 201 Created | |||
Location: https://example.com/upload/b530ce8ff | Location: https://example.com/upload/b530ce8ff | |||
Upload-Limit: max-size=1000000000 | Upload-Limit: max-size=1000000000 | |||
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. | |||
POST /upload HTTP/1.1 | POST /upload HTTP/1.1 | |||
Host: example.com | Host: example.com | |||
Upload-Complete: ?1 | Upload-Complete: ?1 | |||
Content-Length: 100 | Content-Length: 100000000 | |||
Upload-Length: 100 | Upload-Length: 100000000 | |||
[content (100 bytes)] | [content (100000000 bytes)] | |||
HTTP/1.1 104 Upload Resumption Supported | HTTP/1.1 104 Upload Resumption Supported | |||
Location: https://example.com/upload/b530ce8ff | Location: https://example.com/upload/b530ce8ff | |||
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. The client cannot continue the upload. | the server. The client cannot continue the upload. | |||
POST /upload HTTP/1.1 | POST /upload HTTP/1.1 | |||
Host: example.com | Host: example.com | |||
Upload-Complete: ?1 | Upload-Complete: ?1 | |||
Content-Length: 100 | Content-Length: 100000000 | |||
Upload-Length: 100 | Upload-Length: 100000000 | |||
[content (100 bytes)] | [content (100000000 bytes)] | |||
HTTP/1.1 400 Bad Request | HTTP/1.1 400 Bad Request | |||
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 received 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 | |||
skipping to change at page 19, line 12 ¶ | skipping to change at page 20, line 12 ¶ | |||
to connectivity issues, the client MAY retry retrieving the | to connectivity issues, the client MAY retry retrieving the | |||
offset. | offset. | |||
4.3.2. Server Behavior | 4.3.2. Server Behavior | |||
A successful response to a "HEAD" request against an upload resource | A successful response to a "HEAD" request against an upload resource | |||
o MUST include the offset in the "Upload-Offset" header field | o MUST include the offset in the "Upload-Offset" header field | |||
(Section 4.1.1), | (Section 4.1.1), | |||
o MUST include the completeless state in the "Upload-Complete" | o MUST include the completeness state in the "Upload-Complete" | |||
header field (Section 4.1.2), | header field (Section 4.1.2), | |||
o MUST include the length in the "Upload-Length" header field if | o MUST include the length in the "Upload-Length" header field if | |||
known (Section 4.1.3), | known (Section 4.1.3), | |||
o MUST indicate the limits in the "Upload-Limit" header field | o MUST indicate the limits in the "Upload-Limit" header field | |||
(Section 4.1.4), and | (Section 4.1.4), and | |||
o SHOULD include the "Cache-Control" header field with the value | o SHOULD include the "Cache-Control" header field with the value | |||
"no-store" to prevent HTTP caching ([CACHING]). | "no-store" to prevent HTTP caching ([CACHING]). | |||
The resource SHOULD NOT generate a response with the "301 (Moved | The resource 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 "HEAD" method. | follow the redirect without preserving the "HEAD" method. | |||
4.3.3. Example | 4.3.3. Examples | |||
A) The following example shows an offset retrieval request. The | A) The following example shows an offset retrieval request. The | |||
server indicates the current offset and that the upload is not | server indicates the current offset and that the upload is not | |||
complete yet. The client can continue to append representation data. | complete yet. The client can continue to append representation data. | |||
HEAD /upload/b530ce8ff HTTP/1.1 | HEAD /upload/b530ce8ff HTTP/1.1 | |||
Host: example.com | Host: example.com | |||
HTTP/1.1 204 No Content | HTTP/1.1 204 No Content | |||
Upload-Offset: 100 | Upload-Offset: 25000000 | |||
Upload-Complete: ?0 | Upload-Complete: ?0 | |||
Upload-Length: 500 | Upload-Length: 100000000 | |||
Upload-Limit: max-age=3600 | Upload-Limit: max-age=3600 | |||
Cache-Control: no-store | Cache-Control: no-store | |||
B) The following example shows on offset retrieval request for a | B) The following example shows an offset retrieval request for a | |||
completed upload. The client does not need to continue the upload. | completed upload. The client does not need to continue the upload. | |||
HEAD /upload/b530ce8ff HTTP/1.1 | HEAD /upload/b530ce8ff HTTP/1.1 | |||
Host: example.com | Host: example.com | |||
HTTP/1.1 204 No Content | HTTP/1.1 204 No Content | |||
Upload-Offset: 500 | Upload-Offset: 100000000 | |||
Upload-Complete: ?1 | Upload-Complete: ?1 | |||
Upload-Length: 500 | 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" request header | |||
field. To ensure that the upload resource will accept request, the | field. To ensure that the upload resource will accept the request, | |||
offset SHOULD be taken from an immediate previous response for | the 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 if the end of the request content is the end of the | value is true if the end of the request content is the end of the | |||
representation data. If the content is then fully received by the | representation data. If the content is then fully received by the | |||
upload resource, the upload will be complete. | upload resource, the upload will be complete. | |||
The request content can be empty. If the "Upload-Complete" field is | The request content can be empty. If the "Upload-Complete" field is | |||
then set to true, the client wants to complete the upload without | then set to true, the client wants to complete the upload without | |||
appending additional representation data. | appending additional representation data. | |||
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 remaining representation | o "2xx (Successful)" status code and the remaining representation | |||
data was transferred in the request content, the upload is | data was transferred in the request content, the upload is | |||
complete and the corresponding response belongs to the resource | complete and the corresponding response belongs to the resource | |||
processing the representation according to the initial request | processing the representation according to the initial request | |||
(see Section 4.2). | (see Section 4.2). | |||
o "2xx (Successful)" status code and not the entire remaining | o "2xx (Successful)" status code and the entire remaining | |||
representation data was transferred in the request content, the | representation data was not transferred in the request content, | |||
client can continue appending representation data. | the client can continue appending representation data. | |||
o "307 (Temporary Redirect)" or "308 (Permanent Redirect)" status | o "307 (Temporary Redirect)" or "308 (Permanent Redirect)" status | |||
code, the client MAY retry appending to the new URI. | code, the client MAY retry appending to the new URI. | |||
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 | |||
skipping to change at page 22, line 31 ¶ | skipping to change at page 23, line 31 ¶ | |||
resource invalid and rejecting any further interaction with it. It | resource invalid and rejecting any further interaction with it. It | |||
is not sufficient to rely on the "Content-Length" header field for | is not sufficient to rely on the "Content-Length" header field for | |||
enforcement because the header field might not be present. | enforcement because the header field might not be present. | |||
While the request content is being received, the server SHOULD send | While the request content is being received, 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. Example | 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 100 bytes at an offset of 100 and does not | transfers the next 25000000 bytes at an offset of 25000000 and does | |||
indicate that the upload is then completed. The server generates one | not indicate that the upload is then completed. The server generates | |||
interim response and finally acknowledges the new offset: | one interim response and finally acknowledges the new offset: | |||
PATCH /upload/b530ce8ff HTTP/1.1 | PATCH /upload/b530ce8ff HTTP/1.1 | |||
Host: example.com | Host: example.com | |||
Upload-Complete: ?0 | Upload-Complete: ?0 | |||
Upload-Offset: 100 | Upload-Offset: 25000000 | |||
Content-Length: 100 | Content-Length: 25000000 | |||
Content-Type: application/partial-upload | Content-Type: application/partial-upload | |||
[content (100 bytes)] | [content (25000000 bytes)] | |||
HTTP/1.1 104 Upload Resumption Supported | HTTP/1.1 104 Upload Resumption Supported | |||
Upload-Offset: 150 | Upload-Offset: 12500000 | |||
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 200 bytes and completes the upload. The | transfers the remaining 25000000 bytes and completes the upload. The | |||
server processes the uploaded representation and generates the | server processes the uploaded representation and generates the | |||
responding response, in this example containing extracted meta data: | responding response, in this example containing extracted meta data: | |||
PATCH /upload/b530ce8ff HTTP/1.1 | PATCH /upload/b530ce8ff HTTP/1.1 | |||
Host: example.com | Host: example.com | |||
Upload-Complete: ?1 | Upload-Complete: ?1 | |||
Upload-Offset: 200 | Upload-Offset: 25000000 | |||
Content-Length: 100 | Content-Length: 25000000 | |||
Content-Type: application/partial-upload | Content-Type: application/partial-upload | |||
[content (100 bytes)] | [content (25000000 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 24, line 21 ¶ | skipping to change at page 25, line 21 ¶ | |||
HTTP/1.1 204 No Content | HTTP/1.1 204 No Content | |||
4.6. Concurrency | 4.6. Concurrency | |||
Resumable uploads, as defined in this document, do not permit | Resumable uploads, as defined in this document, do not permit | |||
uploading representation data in parallel to the same upload | uploading representation data in parallel to the same upload | |||
resource. The client MUST NOT perform multiple representation data | resource. The client MUST NOT perform multiple representation data | |||
transfers for the same upload resource in parallel. | transfers for the same upload resource in parallel. | |||
Even if the client is well behaving and doesn't send concurrent | Even if the client is well-behaved and doesn't send concurrent | |||
requests, network interruptions can occur in such a way that the | requests, network interruptions can occur in such a way that the | |||
client considers a request as failed while the server is unaware of | client considers a request as failed while the server is unaware of | |||
the problem and considers the request still ongoing. The client | the problem and considers the request still ongoing. The client | |||
might then try to resume the upload with the best intentions, | might then try to resume the upload with the best intentions, | |||
resulting in concurrent requests from the server's perspective. | resulting in concurrent requests from the server's perspective. | |||
Therefore, the server MUST take measures to prevent race conditions, | Therefore, the server MUST take measures to prevent race conditions, | |||
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 | |||
skipping to change at page 25, line 39 ¶ | skipping to change at page 26, line 39 ¶ | |||
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 receive by the server. In addition, clients can use this | of data received by the server. In addition, clients can use this | |||
information to release representation data that was buffered, | 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. | |||
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 | |||
resource. There is no minimum block size and the block might be | resource. There is no minimum block size and the block might be | |||
empty. The block can be a subset of the representation data, where | empty. The block can be a subset of the representation data, where | |||
the start and/or end of the block don't line up with the start and/or | the start and/or end of the block don't line up with the start and/or | |||
skipping to change at page 26, line 22 ¶ | skipping to change at page 27, line 22 ¶ | |||
(Section 4.4) to indicate that the "Upload-Offset" header field in | (Section 4.4) to indicate that the "Upload-Offset" header field in | |||
the request does not match the upload resource's offset. | the request does not match the upload resource's offset. | |||
Two problem type extension members are defined: the "expected-offset" | Two problem type extension members are defined: the "expected-offset" | |||
and "provided-offset" members. A response using this problem type | and "provided-offset" members. A response using this problem type | |||
SHOULD populate both members, with the value of "expected-offset" | SHOULD populate both members, with the value of "expected-offset" | |||
taken from the upload resource and the value of "provided-offset" | taken from the upload resource and the value of "provided-offset" | |||
taken from the upload append request. | taken from the upload append request. | |||
The following example shows an example response, where the resource's | The following example shows an example response, where the resource's | |||
offset was 100, but the client attempted to append at offset 200: | offset was 12500000, but the client attempted to append at offset | |||
25000000: | ||||
# NOTE: '\' line wrapping per RFC 8792 | # NOTE: '\' line wrapping per RFC 8792 | |||
HTTP/1.1 409 Conflict | HTTP/1.1 409 Conflict | |||
Content-Type: application/problem+json | Content-Type: application/problem+json | |||
{ | { | |||
"type":"https://iana.org/assignments/http-problem-types#\ | "type":"https://iana.org/assignments/http-problem-types#\ | |||
mismatching-upload-offset", | mismatching-upload-offset", | |||
"title": "offset from request does not match offset of resource", | "title": "offset from request does not match offset of resource", | |||
"expected-offset": 100, | "expected-offset": 12500000, | |||
"provided-offset": 200 | "provided-offset": 25000000 | |||
} | } | |||
7.2. Completed Upload | 7.2. Completed Upload | |||
This section defines the "https://iana.org/assignments/http-problem- | This section defines the "https://iana.org/assignments/http-problem- | |||
types#completed-upload" problem type [PROBLEM]. A server can use | types#completed-upload" problem type [PROBLEM]. A server can use | |||
this problem type when responding to an upload append request | this problem type when responding to an upload append request | |||
(Section 4.4) to indicate that the upload has already been completed | (Section 4.4) to indicate that the upload has already been completed | |||
and cannot be modified. | and cannot be modified. | |||
skipping to change at page 28, line 26 ¶ | skipping to change at page 29, line 26 ¶ | |||
Encoding" header field. | Encoding" header field. | |||
10. Integrity Digests | 10. Integrity Digests | |||
The integrity of an entire upload or individual upload requests can | The integrity of an entire upload or individual upload requests can | |||
be verifying using digests from [DIGEST-FIELDS]. | be verifying using digests from [DIGEST-FIELDS]. | |||
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 strech | representation data that has been uploaded so far, which might | |||
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 received representation data and compare it to the provided | |||
digest. If the digests don't match, the server SHOULD consider the | digest. If the digests don't match, the server SHOULD consider the | |||
upload failed, not process the representation further, and signal the | upload 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. | |||
skipping to change at page 29, line 26 ¶ | skipping to change at page 30, line 26 ¶ | |||
the integrity digest of the received content and compare it to the | the integrity digest of the received content and compare it to the | |||
provided digest. If the digests don't match the server SHOULD | provided digest. If the digests don't match the server SHOULD | |||
consider the transfer failed, not append the content to the upload | consider the transfer failed, not append the content to the upload | |||
resource, and signal the failure to the client. This way, the | resource, and signal the failure to the client. This way, the | |||
integrity of an individual request can be protected. | integrity of an 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 similar 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, which 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 upload resource might | |||
receive the remaining representation data, complete the upload, and | receive the remaining representation data, complete the upload, and | |||
send a response to the client, which then does not receive the | send a response to the client, which then does not receive the | |||
response. The client can learn that the upload is complete by | response. The client can learn that the upload is complete by | |||
retrieving its state (Section 4.3), but resumable uploads as defined | retrieving its state (Section 4.3), but resumable uploads as defined | |||
skipping to change at page 30, line 35 ¶ | skipping to change at page 31, line 35 ¶ | |||
interim responses. An upload creation request then includes the full | interim responses. An upload creation request then includes the full | |||
representation data because the client anticipates that it will be | representation data because the client anticipates that it will be | |||
transferred without interruptions or resumed if an interruption | transferred without interruptions or resumed if an interruption | |||
occurs. | 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 received 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 server | |||
does not support resumable uploads at all, the server does not | does not support resumable uploads at all, the server does not | |||
support sending the "104 (Upload Resumption Supported)" interim | support sending the "104 (Upload Resumption Supported)" interim | |||
response, or an intermediary dropped the interim response. Without a | response, or an intermediary dropped the interim response. Without a | |||
104 response, the client needs to either treat the upload as failed | 104 response, the client needs to either treat the upload as failed | |||
or retry the entire upload creation request if this is allowed by the | or retry the entire upload creation request if this is allowed by the | |||
application. | application. | |||
skipping to change at page 31, line 13 ¶ | skipping to change at page 32, line 13 ¶ | |||
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 | |||
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 offer 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 | A server that supports resumable uploads at the target URI can create | |||
an upload resource and send its URI in a "104 (Upload Resumption | an upload resource and send its URI in a "104 (Upload Resumption | |||
Supported)" interim response for the client to resume the upload | Supported)" interim response for the client to resume the upload | |||
after interruptions. A server that does not support resumable | after interruptions. A server that does not support resumable | |||
uploads or does not want to upgrade to a resumable upload for this | uploads or does not want to upgrade to a resumable upload for this | |||
skipping to change at page 33, line 7 ¶ | skipping to change at page 34, line 7 ¶ | |||
them alive by regularly sending "PATCH" requests with no or small | them alive by regularly sending "PATCH" requests with no or small | |||
content to the upload resources. This could be abused to exhaust | content to the upload resources. This could be abused to exhaust | |||
server resources by creating and holding open uploads indefinitely | server resources by creating and holding open uploads indefinitely | |||
with minimal work. Servers SHOULD provide mitigations for Slowloris | with minimal work. Servers SHOULD provide mitigations for Slowloris | |||
attacks, such as increasing the maximum number of clients the server | attacks, such as increasing the maximum number of clients the server | |||
will allow, limiting the number of uploads a single client is allowed | will allow, limiting the number of uploads a single client is allowed | |||
to make, imposing restrictions on the minimum transfer speed an | to make, imposing restrictions on the minimum transfer speed an | |||
upload is allowed to have, and restricting the length of time an | upload is allowed to have, and restricting the length of time an | |||
upload resource can exist. | upload resource can exist. | |||
Uploads performed as a series of appends can be used to upload data | ||||
up to the "max-size" limit, which could be a larger size than a | ||||
server or intermediary might normally permit in conventional single | ||||
upload request message content. Servers or intermediaries need to | ||||
consider that relying solely on message content limits to constrain | ||||
resources allocated to uploads might not an effective strategy when | ||||
using resumable uploads. | ||||
14. IANA Considerations | 14. IANA Considerations | |||
14.1. HTTP Fields | 14.1. HTTP Fields | |||
IANA is asked to register the following entries in the "Hypertext | IANA is asked to register the following entries in the "Hypertext | |||
Transfer Protocol (HTTP) Field Name Registry": | Transfer Protocol (HTTP) Field Name Registry": | |||
+-----------------+-----------+-------------+-----------------------+ | +-----------------+-----------+-------------+-----------------------+ | |||
| Field Name | Status | Structured | Reference | | | Field Name | Status | Structured | Reference | | |||
| | | Type | | | | | | Type | | | |||
skipping to change at page 37, line 13 ¶ | skipping to change at page 38, 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-08 | A.1. Since draft-ietf-httpbis-resumable-upload-09 | |||
None yet | ||||
A.2. 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.2. Since draft-ietf-httpbis-resumable-upload-07 | A.3. 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.3. Since draft-ietf-httpbis-resumable-upload-06 | A.4. 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.4. Since draft-ietf-httpbis-resumable-upload-05 | A.5. 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.5. Since draft-ietf-httpbis-resumable-upload-04 | A.6. 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.6. Since draft-ietf-httpbis-resumable-upload-03 | A.7. 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.7. Since draft-ietf-httpbis-resumable-upload-02 | A.8. 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.8. Since draft-ietf-httpbis-resumable-upload-01 | A.9. 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.9. Since draft-ietf-httpbis-resumable-upload-00 | A.10. 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.10. Since draft-tus-httpbis-resumable-uploads-protocol-02 | A.11. Since draft-tus-httpbis-resumable-uploads-protocol-02 | |||
None | None | |||
A.11. Since draft-tus-httpbis-resumable-uploads-protocol-01 | A.12. 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.12. Since draft-tus-httpbis-resumable-uploads-protocol-00 | A.13. 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. 70 change blocks. | ||||
160 lines changed or deleted | 215 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/ |