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/