draft-ietf-httpbis-resumable-upload-05.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: April 24, 2025 Apple Inc. Expires: August 20, 2025 Apple Inc.
L. Pardue, Ed. L. Pardue, Ed.
Cloudflare Cloudflare
October 21, 2024 February 16, 2025
Resumable Uploads for HTTP Resumable Uploads for HTTP
draft-ietf-httpbis-resumable-upload-05 draft-ietf-httpbis-resumable-upload-latest
Abstract Abstract
HTTP clients often encounter interrupted data transfers as a result HTTP clients often encounter interrupted data transfers as a result
of canceled requests or dropped connections. Prior to interruption, of canceled requests or dropped connections. Prior to interruption,
part of a representation may have been exchanged. To complete the part of a representation may have been exchanged. To complete the
data transfer of the entire representation, it is often desirable to transfer of the entire representation, it is often desirable to issue
issue subsequent requests that transfer only the remainder of the subsequent requests that transfer only the remainder of the
representation. HTTP range requests support this concept of representation. HTTP range requests support this concept of
resumable downloads from server to client. This document describes a resumable downloads from server to client. This document describes a
mechanism that supports resumable uploads from client to server using mechanism that supports resumable uploads from client to server using
HTTP. 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
skipping to change at page 2, line 12 skipping to change at page 2, line 12
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 April 24, 2025. This Internet-Draft will expire on August 20, 2025.
Copyright Notice Copyright Notice
Copyright (c) 2024 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 . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Conventions and Definitions . . . . . . . . . . . . . . . . . 4 2. Conventions and Definitions . . . . . . . . . . . . . . . . . 4
3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 4 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 4
3.1. Example 1: Complete upload of file with known size . . . 5 3.1. Example 1: Complete upload of representation data with
known size . . . . . . . . . . . . . . . . . . . . . . . 5
3.2. Example 2: Upload as a series of parts . . . . . . . . . 7 3.2. Example 2: Upload as a series of parts . . . . . . . . . 7
4. Upload Creation . . . . . . . . . . . . . . . . . . . . . . . 8 4. Upload Creation . . . . . . . . . . . . . . . . . . . . . . . 8
4.1. Feature Detection . . . . . . . . . . . . . . . . . . . . 11 4.1. Feature Detection . . . . . . . . . . . . . . . . . . . . 11
4.2. Draft Version Identification . . . . . . . . . . . . . . 12 4.2. Draft Version Identification . . . . . . . . . . . . . . 12
5. Offset Retrieval . . . . . . . . . . . . . . . . . . . . . . 12 5. Offset Retrieval . . . . . . . . . . . . . . . . . . . . . . 12
6. Upload Append . . . . . . . . . . . . . . . . . . . . . . . . 14 6. Upload Append . . . . . . . . . . . . . . . . . . . . . . . . 14
7. Upload Cancellation . . . . . . . . . . . . . . . . . . . . . 17 7. Upload Cancellation . . . . . . . . . . . . . . . . . . . . . 17
8. Header Fields . . . . . . . . . . . . . . . . . . . . . . . . 18 8. Header Fields . . . . . . . . . . . . . . . . . . . . . . . . 18
8.1. Upload-Offset . . . . . . . . . . . . . . . . . . . . . . 18 8.1. Upload-Offset . . . . . . . . . . . . . . . . . . . . . . 18
8.2. Upload-Limit . . . . . . . . . . . . . . . . . . . . . . 18 8.2. Upload-Limit . . . . . . . . . . . . . . . . . . . . . . 18
8.3. Upload-Complete . . . . . . . . . . . . . . . . . . . . . 19 8.3. Upload-Complete . . . . . . . . . . . . . . . . . . . . . 19
8.4. Upload-Length . . . . . . . . . . . . . . . . . . . . . . 19 8.4. Upload-Length . . . . . . . . . . . . . . . . . . . . . . 19
9. Media Type application/partial-upload . . . . . . . . . . . . 19 9. Media Type application/partial-upload . . . . . . . . . . . . 19
10. Problem Types . . . . . . . . . . . . . . . . . . . . . . . . 19 10. Problem Types . . . . . . . . . . . . . . . . . . . . . . . . 20
10.1. Mismatching Offset . . . . . . . . . . . . . . . . . . . 19 10.1. Mismatching Offset . . . . . . . . . . . . . . . . . . . 20
10.2. Completed Upload . . . . . . . . . . . . . . . . . . . . 20 10.2. Completed Upload . . . . . . . . . . . . . . . . . . . . 20
11. Offset values . . . . . . . . . . . . . . . . . . . . . . . . 20
11. Offset values . . . . . . . . . . . . . . . . . . . . . . . . 21
12. Redirection . . . . . . . . . . . . . . . . . . . . . . . . . 21 12. Redirection . . . . . . . . . . . . . . . . . . . . . . . . . 21
13. Content Codings . . . . . . . . . . . . . . . . . . . . . . . 21 13. Content Codings . . . . . . . . . . . . . . . . . . . . . . . 21
14. Transfer Codings . . . . . . . . . . . . . . . . . . . . . . 21 14. Transfer Codings . . . . . . . . . . . . . . . . . . . . . . 22
15. Integrity Digests . . . . . . . . . . . . . . . . . . . . . . 22 15. Integrity Digests . . . . . . . . . . . . . . . . . . . . . . 22
15.1. Representation Digests . . . . . . . . . . . . . . . . . 22 15.1. Representation Digests . . . . . . . . . . . . . . . . . 22
15.2. Content Digests . . . . . . . . . . . . . . . . . . . . 22 15.2. Content Digests . . . . . . . . . . . . . . . . . . . . 23
16. Subsequent Resources . . . . . . . . . . . . . . . . . . . . 23 16. Subsequent Resources . . . . . . . . . . . . . . . . . . . . 23
17. Upload Strategies . . . . . . . . . . . . . . . . . . . . . . 23 17. Upload Strategies . . . . . . . . . . . . . . . . . . . . . . 23
17.1. Optimistic Upload Creation . . . . . . . . . . . . . . . 23 17.1. Optimistic Upload Creation . . . . . . . . . . . . . . . 24
17.1.1. Upgrading To Resumable Uploads . . . . . . . . . . . 24 17.1.1. Upgrading To Resumable Uploads . . . . . . . . . . . 24
17.2. Careful Upload Creation . . . . . . . . . . . . . . . . 24 17.2. Careful Upload Creation . . . . . . . . . . . . . . . . 25
18. Security Considerations . . . . . . . . . . . . . . . . . . . 25 18. Security Considerations . . . . . . . . . . . . . . . . . . . 25
19. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26 19. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26
20. References . . . . . . . . . . . . . . . . . . . . . . . . . 28 20. References . . . . . . . . . . . . . . . . . . . . . . . . . 28
20.1. Normative References . . . . . . . . . . . . . . . . . . 28 20.1. Normative References . . . . . . . . . . . . . . . . . . 28
20.2. Informative References . . . . . . . . . . . . . . . . . 29 20.2. Informative References . . . . . . . . . . . . . . . . . 29
Appendix A. Informational Response . . . . . . . . . . . . . . . 29 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 29
Appendix B. Feature Detection . . . . . . . . . . . . . . . . . 30 Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Appendix C. Upload Metadata . . . . . . . . . . . . . . . . . . 32 B.1. Since draft-ietf-httpbis-resumable-upload-05 . . . . . . 30
Appendix D. FAQ . . . . . . . . . . . . . . . . . . . . . . . . 32 B.2. Since draft-ietf-httpbis-resumable-upload-04 . . . . . . 30
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 32 B.3. Since draft-ietf-httpbis-resumable-upload-03 . . . . . . 30
Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 B.4. Since draft-ietf-httpbis-resumable-upload-02 . . . . . . 31
F.1. Since draft-ietf-httpbis-resumable-upload-04 . . . . . . 33 B.5. Since draft-ietf-httpbis-resumable-upload-01 . . . . . . 31
F.2. Since draft-ietf-httpbis-resumable-upload-03 . . . . . . 33 B.6. Since draft-ietf-httpbis-resumable-upload-00 . . . . . . 31
F.3. Since draft-ietf-httpbis-resumable-upload-02 . . . . . . 33 B.7. Since draft-tus-httpbis-resumable-uploads-protocol-02 . . 31
F.4. Since draft-ietf-httpbis-resumable-upload-01 . . . . . . 34 B.8. Since draft-tus-httpbis-resumable-uploads-protocol-01 . . 31
F.5. Since draft-ietf-httpbis-resumable-upload-00 . . . . . . 34 B.9. Since draft-tus-httpbis-resumable-uploads-protocol-00 . . 32
F.6. Since draft-tus-httpbis-resumable-uploads-protocol-02 . . 34 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 32
F.7. Since draft-tus-httpbis-resumable-uploads-protocol-01 . . 34
F.8. Since draft-tus-httpbis-resumable-uploads-protocol-00 . . 34
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 34
1. Introduction 1. Introduction
HTTP clients often encounter interrupted data transfers as a result HTTP clients often encounter interrupted data transfers as a result
of canceled requests or dropped connections. Prior to interruption, of canceled requests or dropped connections. Prior to interruption,
part of a representation (see Section 3.2 of [HTTP]) might have been part of a representation (see Section 3.2 of [HTTP]) might have been
exchanged. To complete the data transfer of the entire exchanged. To complete the transfer of the entire representation, it
representation, it is often desirable to issue subsequent requests is often desirable to issue subsequent requests that transfer only
that transfer only the remainder of the representation. HTTP range the remainder of the representation. HTTP range requests (see
requests (see Section 14 of [HTTP]) support this concept of resumable Section 14 of [HTTP]) support this concept of resumable downloads
downloads from server to client. from server to client.
HTTP methods such as POST or PUT can be used by clients to request HTTP methods such as POST or PUT can be used by clients to request
processing of representation data enclosed in the request message. processing of representation data enclosed in the request message.
The transfer of representation data from client to server is often The transfer of representation data from client to server is often
referred to as an upload. Uploads are just as likely as downloads to referred to as an upload. Uploads are just as likely as downloads to
suffer from the effects of data transfer interruption. Humans can suffer from the effects of data transfer interruption. Humans can
play a role in upload interruptions through manual actions such as play a role in upload interruptions through manual actions such as
pausing an upload. Regardless of the cause of an interruption, pausing an upload. Regardless of the cause of an interruption,
servers may have received part of the representation before its servers may have received part of the representation data before its
occurrence and it is desirable if clients can complete the data occurrence and it is desirable if clients can complete the data
transfer by sending only the remainder of the representation. The transfer by sending only the remainder of the representation data.
process of sending additional parts of a representation using The process of sending additional parts of a representation using
subsequent HTTP requests from client to server is herein referred to subsequent HTTP requests from client to server is herein referred to
as a resumable upload. as a resumable upload.
Connection interruptions are common and the absence of a standard Connection interruptions are common and the absence of a standard
mechanism for resumable uploads has lead to a proliferation of custom mechanism for resumable uploads has lead to a proliferation of custom
solutions. Some of those use HTTP, while others rely on other solutions. Some of those use HTTP, while others rely on other
transfer mechanisms entirely. An HTTP-based standard solution is transfer mechanisms entirely. An HTTP-based standard solution is
desirable for such a common class of problem. desirable for such a common class of problem.
This document defines an optional mechanism for HTTP that enables This document defines an optional mechanism for HTTP that enables
resumable uploads in a way that is backwards-compatible with resumable uploads 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 data. Alternatively, they can information to send the remaining representation data.
cancel the upload entirely. Different from ranged downloads, this Alternatively, they can cancel the upload entirely. Different from
protocol does not support transferring different parts of the same ranged downloads, this protocol does not support transferring
representation in parallel. different parts of the same representation in parallel.
2. Conventions and Definitions 2. Conventions and Definitions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in "OPTIONAL" in this document are to be interpreted as described in
BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
The terms Byte Sequence, Item, String, Token, Integer, and Boolean The terms Byte Sequence, Item, String, Token, Integer, and Boolean
are imported from [STRUCTURED-FIELDS]. are imported from [STRUCTURED-FIELDS].
The terms "representation", "representation data", "representation The terms "representation", "representation data", "representation
metadata", "content", "client" and "server" are from [HTTP]. metadata", "content", "client" and "server" are from [HTTP].
The term "patch document" is taken from [PATCH].
3. Overview 3. Overview
Resumable uploads are supported in HTTP through use of a temporary Resumable uploads are supported in HTTP through use of a temporary
resource, an _upload resource_, that is separate from the resource resource, an _upload resource_, that is separate from the resource
being uploaded to (hereafter, the _target resource_) and specific to being uploaded to (hereafter, the _target resource_) and specific to
that upload. By interacting with the upload resource, a client can that upload. By interacting with the upload resource, a client can
retrieve the current offset of the upload (Section 5), append to the retrieve the current offset of the upload (Section 5), append to the
upload (Section 6), and cancel the upload (Section 7). upload (Section 6), and cancel the upload (Section 7).
The remainder of this section uses an example of a file upload to The remainder of this section uses examples to illustrate different
illustrate different interactions with the upload resource. Note, interactions with the upload resource. HTTP message exchanges, and
however, that HTTP message exchanges use representation data (see thereby resumable uploads, use representation data (see Section 8.1
Section 8.1 of [HTTP]), which means that resumable uploads can be of [HTTP]). This means that resumable uploads can be used with many
used with many forms of content -- not just static files. forms of content, such as static files, in-memory buffers, data from
streaming sources, or on-demand generated data.
3.1. Example 1: Complete upload of file with known size 3.1. Example 1: Complete upload of representation data with known size
In this example, the client first attempts to upload a file with a In this example, the client first attempts to upload representation
known size in a single HTTP request to the target resource. An data with a known size in a single HTTP request to the target
interruption occurs and the client then attempts to resume the upload resource. An interruption occurs and the client then attempts to
using subsequent HTTP requests to the upload resource. resume the upload using subsequent HTTP requests to the upload
resource.
1) The client notifies the server that it wants to begin an upload 1) The client notifies the server that it wants to begin an upload
(Section 4). The server reserves the required resources to accept (Section 4). The server reserves the required resources to accept
the upload from the client, and the client begins transferring the the upload from the client, and the client begins transferring the
entire file in the request content. entire representation data in the request content.
An informational response can be sent to the client, which signals An informational response can be sent to the client, which signals
the server's support of resumable upload as well as the upload the server's support of resumable upload as well as the upload
resource URL via the Location header field (Section 10.2.2 of resource URL via the Location header field (Section 10.2.2 of
[HTTP]). [HTTP]).
Client Server Client Server
| | | |
| POST | | POST |
|------------------------------------------->| |------------------------------------------->|
skipping to change at page 5, line 51 skipping to change at page 6, line 4
|<-------------------------------------------| |<-------------------------------------------|
| | | |
| Flow Interrupted | | Flow Interrupted |
|------------------------------------------->| |------------------------------------------->|
| | | |
Figure 1: Upload Creation Figure 1: Upload Creation
2) If the connection to the server is interrupted, the client might 2) If the connection to the server is interrupted, the client might
want to resume the upload. However, before this is possible the want to resume the upload. However, before this is possible the
client needs to know the amount of data that the server received client needs to know the amount of representation data that the
before the interruption. It does so by retrieving the offset server received before the interruption. It does so by retrieving
(Section 5) from the upload resource. the offset (Section 5) from the upload resource.
Client Server Client Server
| | | |
| HEAD to upload resource URL | | HEAD to upload resource URL |
|------------------------------------------------>| |------------------------------------------------>|
| | | |
| 204 No Content with Upload-Offset | | 204 No Content with Upload-Offset |
|<------------------------------------------------| |<------------------------------------------------|
| | | |
Figure 2: Offset Retrieval Figure 2: Offset Retrieval
3) The client can resume the upload by sending the remaining file 3) The client can resume the upload by sending the remaining
content to the upload resource (Section 6), appending to the already representation data to the upload resource (Section 6), appending to
stored data in the upload. The "Upload-Offset" value is included to the already stored representation data in the upload. The "Upload-
ensure that the client and server agree on the offset that the upload Offset" value is included to ensure that the client and server agree
resumes from. on the offset that the upload resumes from.
Client Server Client Server
| | | |
| PATCH to upload resource URL with Upload-Offset | | PATCH to upload resource URL with Upload-Offset |
|------------------------------------------------>| |------------------------------------------------>|
| | | |
| 201 Created on completion | | 201 Created on completion |
|<------------------------------------------------| |<------------------------------------------------|
| | | |
skipping to change at page 7, line 7 skipping to change at page 7, line 7
|------------------------------------------------>| |------------------------------------------------>|
| | | |
| 204 No Content on completion | | 204 No Content on completion |
|<------------------------------------------------| |<------------------------------------------------|
| | | |
Figure 4: Upload Cancellation Figure 4: Upload Cancellation
3.2. Example 2: Upload as a series of parts 3.2. Example 2: Upload as a series of parts
In some cases, clients might prefer to upload a file as a series of In some cases, clients might prefer to upload a representation as a
parts sent serially across multiple HTTP messages. One use case is series of parts sent serially across multiple HTTP messages. One use
to overcome server limits on HTTP message content size. Another use case is to overcome server limits on HTTP message content size.
case is where the client does not know the final size, such as when Another use case is where the client does not know the final size of
file data originates from a streaming source. the representation data, such as when the data originates from a
streaming source.
This example shows how the client, with prior knowledge about the This example shows how the client, with prior knowledge about the
server's resumable upload support, can upload parts of a file server's resumable upload support, can upload parts of a
incrementally. representation incrementally.
1) If the client is aware that the server supports resumable upload, 1) If the client is aware that the server supports resumable upload,
it can start an upload with the "Upload-Complete" field value set to it can start an upload with the "Upload-Complete" field value set to
false and the first part of the file. false and the first part of the representation.
Client Server Client Server
| | | |
| POST with Upload-Complete: ?0 | | POST with Upload-Complete: ?0 |
|------------------------------------------------>| |------------------------------------------------>|
| | | |
| 201 Created with Upload-Complete: ?0 | | 201 Created with Upload-Complete: ?0 |
| and Location on completion | | and Location on completion |
|<------------------------------------------------| |<------------------------------------------------|
| | | |
skipping to change at page 8, line 19 skipping to change at page 8, line 19
of resources, this is accomplished by including the "Upload-Complete" of resources, this is accomplished by including the "Upload-Complete"
header field in the request that initiates the upload. header field in the request that initiates the upload.
As a consequence, resumable uploads support all HTTP request methods As a consequence, resumable uploads support all HTTP request methods
that can carry content, such as "POST", "PUT", and "PATCH". that can carry content, such as "POST", "PUT", and "PATCH".
Similarly, the response to the upload request can have any status Similarly, the response to the upload request can have any status
code. Both the method(s) and status code(s) supported are determined code. Both the method(s) and status code(s) supported are determined
by the resource. by the resource.
"Upload-Complete" MUST be set to false if the end of the request "Upload-Complete" MUST be set to false if the end of the request
content is not the end of the upload. Otherwise, it MUST be set to content is not the end of the representation data. Otherwise, it
true. This header field can be used for request identification by a MUST be set to true. This header field can be used for request
server. The request MUST NOT include the "Upload-Offset" header identification by a server. The request MUST NOT include the
field. "Upload-Offset" header field.
If the request is valid, the server SHOULD create an upload resource. If the request is valid, the server SHOULD create an upload resource.
Then, the server MUST include the "Location" header field in the Then, the server MUST include the "Location" header field in the
response and set its value to the URL of the upload resource. The response and set its value to the URL of the upload resource. The
client MAY use this URL for offset retrieval (Section 5), upload client MAY use this URL for offset retrieval (Section 5), upload
append (Section 6), and upload cancellation (Section 7). append (Section 6), and upload cancellation (Section 7).
Once the upload resource is available and while the request content Once the upload resource is available and while the request content
is being uploaded, the target resource MAY send one or more is being transferred, the target resource MAY send one or more
informational responses with a "104 (Upload Resumption Supported)" informational responses with a "104 (Upload Resumption Supported)"
status code to the client. In the first informational response, the status code to the client. In the first informational response, the
"Location" header field MUST be set to the URL pointing to the upload "Location" header field MUST be set to the URL pointing to the upload
resource. In subsequent informational responses, the "Location" resource. In subsequent informational responses, the "Location"
header field MUST NOT be set. An informational response MAY contain header field MUST NOT be set. An informational response MAY contain
the "Upload-Offset" header field with the current upload offset as the "Upload-Offset" header field with the current upload offset as
the value to inform the client about the upload progress. the value to inform the client about the upload progress.
The server MUST send the "Upload-Offset" header field in the response The server MUST send the "Upload-Offset" header field in the response
if it considers the upload active, either when the response is a if it considers the upload active, either when the response is a
success (e.g. "201 (Created)"), or when the response is a failure success (e.g. "201 (Created)"), or when the response is a failure
(e.g. "409 (Conflict)"). The "Upload-Offset" field value MUST be (e.g. "409 (Conflict)"). The "Upload-Offset" field value MUST be
equal to the end offset of the entire upload, or the begin offset of equal to the end offset of the entire upload, or the begin offset of
the next chunk if the upload is still incomplete. The client SHOULD the next chunk if the upload is still incomplete. The client SHOULD
consider the upload failed if the response has a status code that consider the upload failed if the response has a status code that
indicates a success but the offset indicated in the "Upload-Offset" indicates a success but the offset indicated in the "Upload-Offset"
field value does not equal the total of begin offset plus the number field value does not equal the total of begin offset plus the number
of bytes uploaded in the request. of bytes uploaded in the request.
If the request completes successfully and the entire upload is If the request completes successfully and the entire representation
complete, the server MUST acknowledge it by responding with a 2xx data was transferred, the server MUST acknowledge it by responding
(Successful) status code. Servers are RECOMMENDED to use "201 with a 2xx (Successful) status code. Servers are RECOMMENDED to use
(Created)" unless otherwise specified. The response MUST NOT include "201 (Created)" unless otherwise specified. The response MUST NOT
the "Upload-Complete" header field with the value of false. include the "Upload-Complete" header field with the value of false.
If the request completes successfully but the entire upload is not If the request completes successfully but not the entire
yet complete, as indicated by an "Upload-Complete" field value of representation data was transferred, as indicated by an "Upload-
false in the request, the server MUST acknowledge it by responding Complete" field value of false in the request, the server MUST
with the "201 (Created)" status code and an "Upload-Complete" header acknowledge it by responding with the "201 (Created)" status code and
value set to false. an "Upload-Complete" header value set to false.
The request can indicate the upload's final size in two different The request can indicate the upload's final size in two different
ways. Both indicators may be present in the same request as long as ways. Both indicators may be present in the same request as long as
they convey the same size. If the sizes are inconsistent, the server they convey the same size. If the sizes are inconsistent, the server
MUST reject the request by responding with a "400 (Bad Request)" MUST reject the request by responding with a "400 (Bad Request)"
status code. status code.
o If the request includes an "Upload-Complete" field value set to o If the request includes an "Upload-Complete" field value set to
true and a valid "Content-Length" header field, the client true and a valid "Content-Length" header field, the client
attempts to upload a fixed-length resource in one request. In attempts to upload representation data with a fixed length in one
this case, the upload's final size is the "Content-Length" field request. In this case, the upload's final size is the "Content-
value and the server MUST record it to ensure its consistency. Length" field value and the server MUST record it to ensure its
The value can therefore not be used if the upload is split across consistency. The value can therefore not be used if the upload is
multiple requests. split across multiple requests.
o If the request includes the "Upload-Length" header field, the o If the request includes the "Upload-Length" header field, the
server MUST record its value as the upload's final size. A client server MUST record its value as the upload's final size. A client
SHOULD provide this header field if the upload length is known at SHOULD provide this header field if the length of the
the time of upload creation. representation data is known at the time of upload creation.
The upload is not automatically completed if the offset reaches the The upload is not automatically completed if the offset reaches the
upload's final size. Instead, a client MUST indicate the completion upload's final size. Instead, a client MUST indicate the completion
of an upload through the "Upload-Complete" header field. Indicating of an upload through the "Upload-Complete" header field. Indicating
an upload's final size can help the server allocate necessary an upload's final size can help the server allocate necessary
resources for the upload and provide early feedback if the size does resources for the upload and provide early feedback if the size does
not match the server's limits (Section 8.2). not match the server's limits (Section 8.2).
The server MAY enforce a maximum size of an upload resource. This The server MAY enforce a maximum size of the representation data.
limit MAY be equal to the upload's final size, if available, or an This limit MAY be equal to the upload's final size, if available, or
arbitrary value. The limit's value or its existence MUST NOT change an arbitrary value. The limit's value or its existence MUST NOT
throughout the lifetime of the upload resource. The server MAY change throughout the lifetime of the upload resource. The server
indicate such a limit to the client by including the "Upload-Limit" MAY indicate such a limit to the client by including the "Upload-
header field in the informational or final response to upload Limit" header field in the informational or final response to upload
creation. If the client receives an "Upload-Limit" header field creation. If the client receives an "Upload-Limit" header field
indicating that the maximum size is less than the amount of bytes it indicating that the maximum size is less than the amount of
intends to upload to a resource, it SHOULD stop the current upload representation data it intends to upload to a resource, it SHOULD
transfer immediately and cancel the upload (Section 7). stop the current upload transfer immediately and cancel the upload
(Section 7).
The request content MAY be empty. If the "Upload-Complete" header The request content MAY 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
resource representation. An "Upload-Complete" header field is set to representation. An "Upload-Complete" header field is set to false is
false is also valid. This can be used to create an upload resource also valid. This can be used to create an upload resource URL before
URL before transferring data, which can save client or server transferring any representation data, saving client and server
resources. Since informational responses are optional, this resources. Since informational responses are optional, this
technique provides another mechanism to learn the URL, at the cost of technique provides another mechanism to learn the URL, at the cost of
an additional round-trip before data upload can commence. an additional round-trip before data upload can commence.
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 starting at its SHOULD append as much of the request content starting at its
beginning and without discontinuities as possible. If the server did beginning and without discontinuities as possible. If the server did
not append the entire request content, the upload MUST NOT be not append the entire request content, the upload MUST NOT be
considered complete. considered complete.
skipping to change at page 10, line 46 skipping to change at page 10, line 46
Upload-Offset: 50 Upload-Offset: 50
Upload-Limit: max-size=1000000000 Upload-Limit: max-size=1000000000
HTTP/1.1 201 Created HTTP/1.1 201 Created
Location: https://example.com/upload/b530ce8ff Location: https://example.com/upload/b530ce8ff
Upload-Offset: 100 Upload-Offset: 100
Upload-Limit: max-size=1000000000 Upload-Limit: max-size=1000000000
The next example shows an upload creation, where only the first 25 The next example shows an upload creation, where only the first 25
bytes of a 100 bytes upload are transferred. The server acknowledges bytes of a 100 bytes upload are transferred. The server acknowledges
the received data and that the upload is not complete yet: the received representation data and that the upload is not complete
yet:
POST /upload HTTP/1.1 POST /upload HTTP/1.1
Host: example.com Host: example.com
Upload-Draft-Interop-Version: 6 Upload-Draft-Interop-Version: 6
Upload-Complete: ?0 Upload-Complete: ?0
Content-Length: 25 Content-Length: 25
Upload-Length: 100 Upload-Length: 100
[partial content (25 bytes)] [partial content (25 bytes)]
skipping to change at page 11, line 26 skipping to change at page 11, line 26
Upload-Complete: ?0 Upload-Complete: ?0
Upload-Offset: 25 Upload-Offset: 25
Upload-Limit: max-size=1000000000 Upload-Limit: max-size=1000000000
If the client received an informational response with the upload URL If the client received an informational response with the upload URL
in the Location field value, it MAY automatically attempt upload in the Location field value, it MAY automatically attempt upload
resumption when the connection is terminated unexpectedly, or if a resumption when the connection is terminated unexpectedly, or if a
5xx status is received. The client SHOULD NOT automatically retry if 5xx status is received. The client SHOULD NOT automatically retry if
it receives a 4xx status code. it receives a 4xx status code.
File metadata can affect how servers might act on the uploaded file. Representation metadata can affect how servers might act on the
Clients can send representation metadata (see Section 8.3 of [HTTP]) uploaded representation data. Clients can send representation
in the request that starts an upload. Servers MAY interpret this metadata (see Section 8.3 of [HTTP]) in the request that starts an
metadata or MAY ignore it. The "Content-Type" header field upload. Servers MAY interpret this metadata or MAY ignore it. The
(Section 8.3 of [HTTP]) can be used to indicate the media type of the "Content-Type" header field (Section 8.3 of [HTTP]) can be used to
file. The applied content codings are specified using the "Content- indicate the media type of the representation. The applied content
Encoding" header field and are retained throughout the entire upload. codings are specified using the "Content-Encoding" header field and
When resuming an interrupted upload, the same content codings are are retained throughout the entire upload. When resuming an
used for appending to the upload, producing a representation of the interrupted upload, the same content codings are used for appending
upload resource. The "Content-Disposition" header field ([RFC6266]) to the upload, producing a consistent representation. The "Content-
can be used to transmit a filename; if included, the parameters Disposition" header field ([CONTENT-DISPOSITION]) can be used to
SHOULD be either "filename", "filename*" or "boundary". transmit a filename; if included, the parameters SHOULD be either
"filename", "filename*" or "boundary".
4.1. Feature Detection 4.1. Feature Detection
If the client has no knowledge of whether the resource supports If the client has no knowledge of whether the resource supports
resumable uploads, a resumable request can be used with some resumable uploads, a resumable request can be used with some
additional constraints. In particular, the "Upload-Complete" field additional constraints. In particular, the "Upload-Complete" field
value (Section 8.3) MUST NOT be false if the server support is value (Section 8.3) MUST NOT be false if the server support is
unclear. This allows the upload to function as if it is a regular unclear. This allows the upload to function as if it is a regular
upload. upload.
skipping to change at page 13, line 13 skipping to change at page 13, line 13
upload resource. upload resource.
The request MUST NOT include an "Upload-Offset", "Upload-Complete", The request MUST NOT include an "Upload-Offset", "Upload-Complete",
or "Upload-Length" header field. The server MUST reject requests or "Upload-Length" header field. The server MUST reject requests
with either of these fields by responding with a "400 (Bad Request)" with either of these fields by responding with a "400 (Bad Request)"
status code. status code.
If the server considers the upload resource to be active, it MUST If the server considers the upload resource to be active, it MUST
respond with a "204 (No Content)" or "200 (OK)" status code. The respond with a "204 (No Content)" or "200 (OK)" status code. The
response MUST include the "Upload-Offset" header field, with the response MUST include the "Upload-Offset" header field, with the
value set to the current resumption offset for the target resource. value set to the current resumption offset for the target resource,
which is the number of received bytes of the representation data.
The response MUST include the "Upload-Complete" header field; the The response MUST include the "Upload-Complete" header field; the
value is set to true only if the upload is complete. The response value is set to true only if the upload is complete. The response
MUST include the "Upload-Length" header field set to the upload's MUST include the "Upload-Length" header field set to the upload's
final size if one was recorded during the upload creation final size if one was recorded during the upload creation
(Section 4). The response MAY include the "Upload-Limit" header (Section 4). The response MAY include the "Upload-Limit" header
field if corresponding limits on the upload resource exist. field if corresponding limits on the upload resource exist.
An upload is considered complete only if the server completely and An upload is considered complete only if the server completely and
successfully received a corresponding creation request (Section 4) or successfully received a corresponding creation request (Section 4) or
append request (Section 6) with the "Upload-Complete" header value append request (Section 6) with the "Upload-Complete" header value
set to true. set to true.
The client MUST NOT perform offset retrieval while creation The client MUST NOT perform offset retrieval while creation
(Section 4) or append (Section 6) is in progress. (Section 4) or append (Section 6) is in progress.
The offset MUST be accepted by a subsequent append (Section 6). Due The offset MUST be accepted by a subsequent append (Section 6). Due
to network delay and reordering, the server might still be receiving to network delay and reordering, the server might still be receiving
data from an ongoing transfer for the same upload resource, which in representation data from an ongoing transfer for the same upload
the client's perspective has failed. The server MAY terminate any resource, which in the client's perspective has failed. The server
transfers for the same upload resource before sending the response by MAY terminate any transfers for the same upload resource before
abruptly terminating the HTTP connection or stream. Alternatively, sending the response by abruptly terminating the HTTP connection or
the server MAY keep the ongoing transfer alive but ignore further stream. Alternatively, the server MAY keep the ongoing transfer
bytes received past the offset. alive but ignore further bytes received past the offset.
The client MUST NOT start more than one append (Section 6) based on The client MUST NOT start more than one append (Section 6) based on
the resumption offset from a single offset retrieving request. the resumption offset from a single offset retrieving request.
In order to prevent HTTP caching ([CACHING]), the response SHOULD In order to prevent HTTP caching ([CACHING]), the response SHOULD
include a "Cache-Control" header field with the value "no-store". include a "Cache-Control" header field with the value "no-store".
If the server does not consider the upload resource to be active, it If the server does not consider the upload resource to be active, it
MUST respond with a "404 (Not Found)" status code. MUST respond with a "404 (Not Found)" status code.
The resumption offset can be less than or equal to the number of The resumption offset can be less than or equal to the number of
bytes the client has already sent. The client MAY reject an offset bytes of representation data that the client has already sent. The
which is greater than the number of bytes it has already sent during client MAY reject an offset which is greater than the number of bytes
this upload. The client is expected to handle backtracking of a it has already sent during this upload. The client is expected to
reasonable length. If the offset is invalid for this upload, or if handle backtracking of a reasonable length. If the offset is invalid
the client cannot backtrack to the offset and reproduce the same for this upload, or if the client cannot backtrack to the offset and
content it has already sent, the upload MUST be considered a failure. reproduce the same content it has already sent, the upload MUST be
The client MAY cancel the upload (Section 7) after rejecting the considered a failure. The client MAY cancel the upload (Section 7)
offset. after rejecting the offset.
The following example shows an offset retrieval request. The server The following example shows an offset retrieval request. The server
indicates the new offset and that the upload is not complete yet: indicates the new offset and that the upload is not complete yet:
HEAD /upload/b530ce8ff HTTP/1.1 HEAD /upload/b530ce8ff HTTP/1.1
Host: example.com Host: example.com
Upload-Draft-Interop-Version: 6 Upload-Draft-Interop-Version: 6
HTTP/1.1 204 No Content HTTP/1.1 204 No Content
Upload-Offset: 100 Upload-Offset: 100
skipping to change at page 14, line 32 skipping to change at page 14, line 33
6. Upload Append 6. Upload Append
Upload appending is used for resuming an existing upload. Upload appending is used for resuming an existing upload.
The request MUST use the "PATCH" method with the "application/ The request MUST use the "PATCH" method with the "application/
partial-upload" media type and MUST be sent to the upload resource. partial-upload" media type and MUST be sent to the upload resource.
The "Upload-Offset" field value (Section 8.1) MUST be set to the The "Upload-Offset" field value (Section 8.1) MUST be set to the
resumption offset. resumption offset.
If the end of the request content is not the end of the upload, the If the end of the request content is not the end of the
"Upload-Complete" field value (Section 8.3) MUST be set to false. representation data, the "Upload-Complete" field value (Section 8.3)
MUST be set to false.
The server SHOULD respect representation metadata received during The server SHOULD respect representation metadata received during
creation (Section 4). An upload append request continues uploading creation (Section 4). An upload append request continues uploading
the same representation as used in the upload creation (Section 4) the same representation as used in the upload creation (Section 4)
and thus uses the same content codings, if they were applied. For and thus uses the same content codings, if they were applied. For
example, if the initial upload creation included the "Content- example, if the initial upload creation included the "Content-
Encoding: gzip" header field, the upload append request resumes the Encoding: gzip" header field, the upload append request resumes the
transfer of the gzipped data without indicating again that the gzip transfer of the gzipped representation without indicating again that
coding is applied. the gzip coding is applied.
If the server does not consider the upload associated with the upload If the server does not consider the upload associated with the upload
resource active, it MUST respond with a "404 (Not Found)" status resource active, it MUST respond with a "404 (Not Found)" status
code. code.
The client MUST NOT perform multiple upload transfers for the same The client MUST NOT perform multiple upload transfers for the same
upload resource in parallel. This helps avoid race conditions, and upload resource in parallel. This helps avoid race conditions, and
data loss or corruption. The server is RECOMMENDED to take measures data loss or corruption. The server is RECOMMENDED to take measures
to avoid parallel upload transfers: The server MAY terminate any to avoid parallel upload transfers: The server MAY terminate any
creation (Section 4) or append for the same upload URL. Since the creation (Section 4) or append for the same upload URL. Since the
skipping to change at page 15, line 25 skipping to change at page 15, line 27
"https://iana.org/assignments/http-problem-types#mismatching-upload- "https://iana.org/assignments/http-problem-types#mismatching-upload-
offset" in the response; see Section 10.1. offset" in the response; see Section 10.1.
The server applies the patch document of the "application/partial- The server applies the patch document of the "application/partial-
upload" media type by appending the request content to the targeted upload" media type by appending the request content to the targeted
upload resource. If the server does not receive the entire patch upload resource. If the server does not receive the entire patch
document, for example because of canceled requests or dropped document, for example because of canceled requests or dropped
connections, it SHOULD append as much of the patch document starting connections, it SHOULD append as much of the patch document starting
at its beginning and without discontinuities as possible. Appending at its beginning and without discontinuities as possible. Appending
a continuous section starting at the patch document's beginning a continuous section starting at the patch document's beginning
constitutes a successful PATCH as defined in Section 2 of [RFC5789]. constitutes a successful PATCH as defined in Section 2 of [PATCH].
If the server did not receive and apply the entire patch document, If the server did not receive and apply the entire patch document,
the upload MUST NOT be considered complete. the upload MUST NOT be considered complete.
While the request content is being uploaded, the target resource MAY While the request content is being transferred, the target resource
send one or more informational responses with a "104 (Upload MAY send one or more informational responses with a "104 (Upload
Resumption Supported)" status code to the client. These Resumption Supported)" status code to the client. These
informational responses MUST NOT contain the "Location" header field. informational responses MUST NOT contain the "Location" header field.
They MAY include the "Upload-Offset" header field with the current They MAY include the "Upload-Offset" header field with the current
upload offset as the value to inform the client about the upload upload offset as the value to inform the client about the upload
progress. progress.
The server MUST send the "Upload-Offset" header field in the response The server MUST send the "Upload-Offset" header field in the response
if it considers the upload active, either when the response is a if it considers the upload active, either when the response is a
success (e.g. "201 (Created)"), or when the response is a failure success (e.g. "201 (Created)"), or when the response is a failure
(e.g. "409 (Conflict)"). The value MUST be equal to the end offset (e.g. "409 (Conflict)"). The value MUST be equal to the end offset
skipping to change at page 16, line 5 skipping to change at page 16, line 7
failed if the status code indicates a success but the offset failed if the status code indicates a success but the offset
indicated by the "Upload-Offset" field value does not equal the total indicated by the "Upload-Offset" field value does not equal the total
of begin offset plus the number of bytes uploaded in the request. of begin offset plus the number of bytes uploaded in the request.
If the upload is already complete, the server MUST NOT modify the If the upload is already complete, the server MUST NOT modify the
upload resource and MUST respond with a "400 (Bad Request)" status upload resource and MUST respond with a "400 (Bad Request)" status
code. The server MAY use the problem type [PROBLEM] of code. The server MAY use the problem type [PROBLEM] of
"https://iana.org/assignments/http-problem-types#completed-upload" in "https://iana.org/assignments/http-problem-types#completed-upload" in
the response; see Section 10.2. the response; see Section 10.2.
If the request completes successfully and the entire upload is If the request completes successfully and the entire representation
complete, the server MUST acknowledge it by responding with a 2xx data was transferred, the server MUST acknowledge it by responding
(Successful) status code. Servers are RECOMMENDED to use a "201 with a 2xx (Successful) status code. Servers are RECOMMENDED to use
(Created)" response if not otherwise specified. The response MUST a "201 (Created)" response if not otherwise specified. The response
NOT include the "Upload-Complete" header field with the value set to MUST NOT include the "Upload-Complete" header field with the value
false. set to false.
If the request completes successfully but the entire upload is not If the request completes successfully but not the entire
yet complete indicated by the "Upload-Complete" field value set to representation data was transferred, indicated by the "Upload-
false, the server MUST acknowledge it by responding with a "201 Complete" field value set to false, the server MUST acknowledge it by
(Created)" status code and the "Upload-Complete" field value set to responding with a "201 (Created)" status code and the "Upload-
true. Complete" field value set to false.
If the request includes the "Upload-Complete" field value set to true If the request includes the "Upload-Complete" field value set to true
and a valid "Content-Length" header field, the client attempts to and a valid "Content-Length" header field, the client attempts to
upload the remaining resource in one request. In this case, the upload the remaining representation data in one request. In this
upload's final size is the sum of the upload's offset and the case, the upload's final size is the sum of the upload's offset and
"Content-Length" header field. If the server does not have a record the "Content-Length" header field. If the server does not have a
of the upload's final size from creation or the previous append, the record of the upload's final size from creation or the previous
server MUST record the upload's final size to ensure its consistency. append, the server MUST record the upload's final size to ensure its
If the server does have a previous record, that value MUST match the consistency. If the server does have a previous record, that value
upload's final size. If they do not match, the server MUST reject MUST match the upload's final size. If they do not match, the server
the request with a "400 (Bad Request)" status code. MUST reject the request with a "400 (Bad Request)" status code.
The server MUST prevent that the offset exceeds the upload's final The server MUST prevent that the offset exceeds the upload's final
size when appending. If a final size has been recorded and the size when appending. If a final size has been recorded and the
upload append request exceeds this value, the server MUST stop upload append request exceeds this value, the server MUST stop
appending bytes to the upload once the offset reaches the final size appending bytes to the upload once the offset reaches the final size
and reject the request with a "400 (Bad Request)" status code. It is and reject the request with a "400 (Bad Request)" status code. It is
not sufficient to rely on the "Content-Length" header field for 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.
The request content MAY be empty. If the "Upload-Complete" field is The request content MAY 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 data. appending additional representation data.
The following example shows an upload append. The client transfers The following example shows an upload append. The client transfers
the next 100 bytes at an offset of 100 and does not indicate that the the next 100 bytes at an offset of 100 and does not indicate that the
upload is then completed. The server acknowledges the new offset: upload is then completed. The server acknowledges the new offset:
PATCH /upload/b530ce8ff HTTP/1.1 PATCH /upload/b530ce8ff HTTP/1.1
Host: example.com Host: example.com
Upload-Offset: 100 Upload-Offset: 100
Upload-Draft-Interop-Version: 6 Upload-Draft-Interop-Version: 6
Content-Length: 100 Content-Length: 100
skipping to change at page 18, line 10 skipping to change at page 18, line 16
Host: example.com Host: example.com
Upload-Draft-Interop-Version: 6 Upload-Draft-Interop-Version: 6
HTTP/1.1 204 No Content HTTP/1.1 204 No Content
8. Header Fields 8. Header Fields
8.1. Upload-Offset 8.1. Upload-Offset
The "Upload-Offset" request and response header field indicates the The "Upload-Offset" request and response header field indicates the
resumption offset of corresponding upload, counted in bytes. The resumption offset of corresponding upload, counted in bytes. That is
"Upload-Offset" field value is an Integer. the amount of representation data received by the upload resource.
The "Upload-Offset" field value is an Integer.
8.2. Upload-Limit 8.2. Upload-Limit
The "Upload-Limit" response header field indicates limits applying The "Upload-Limit" response header field indicates limits applying
the upload resource. The "Upload-Limit" field value is a Dictionary. the upload resource. The "Upload-Limit" field value is a Dictionary.
The following limits are defined: The following limits are defined:
o The "max-size" key specifies a maximum size that an upload o The "max-size" key specifies a maximum size that an upload
resource is allowed to reach, counted in bytes. The value is an resource is allowed to reach, counted in bytes. The value is an
Integer. Integer.
o The "min-size" key specifies a minimum size for a resumable o The "min-size" key specifies a minimum size for a resumable
upload, counted in bytes. The server MAY NOT create an upload upload, counted in bytes. The server MAY NOT create an upload
resource if the client indicates that the uploaded data is smaller resource if the client indicates that the representation data is
than the minimum size by including the "Content-Length" and smaller than the minimum size by including the "Content-Length"
"Upload-Complete: ?1" fields, but the server MAY still accept the and "Upload-Complete: ?1" fields, but the server MAY still accept
uploaded data. The value is an Integer. the representation data. The value is an Integer.
o The "max-append-size" key specifies a maximum size counted in o The "max-append-size" key specifies a maximum size counted in
bytes for the request content in a single upload append request bytes for the request content in a single upload append request
(Section 6). The server MAY reject requests exceeding this limit (Section 6). The server MAY reject requests exceeding this limit
and a client SHOULD NOT send larger upload append requests. The and a client SHOULD NOT send larger upload append requests. The
value is an Integer. value is an Integer.
o The "min-append-size" key specifies a minimum size counted in o The "min-append-size" key specifies a minimum size counted in
bytes for the request content in a single upload append request bytes for the request content in a single upload append request
(Section 6) that does not complete the upload by setting the (Section 6) that does not complete the upload by setting the
skipping to change at page 19, line 41 skipping to change at page 19, line 49
8.4. Upload-Length 8.4. Upload-Length
The "Upload-Length" request and response header field indicates the The "Upload-Length" request and response header field indicates the
number of bytes to be uploaded for the corresponding upload resource, number of bytes to be uploaded for the corresponding upload resource,
counted in bytes. The "Upload-Length" field value is an Integer. counted in bytes. The "Upload-Length" field value is an Integer.
9. Media Type application/partial-upload 9. Media Type application/partial-upload
The "application/partial-upload" media type describes a contiguous The "application/partial-upload" media type describes a contiguous
block of data that should be uploaded to a resource. There is no block from the representation data that should be uploaded to a
minimum block size and the block might be empty. The start and end resource. There is no minimum block size and the block might be
of the block might align with the start and end of the file that empty. The start and end of the block might align with the start and
should be uploaded, but they are not required to be aligned. end of the representation data, but they are not required to be
aligned.
10. Problem Types 10. Problem Types
10.1. Mismatching Offset 10.1. Mismatching Offset
This section defines the "https://iana.org/assignments/http-problem- This section defines the "https://iana.org/assignments/http-problem-
types#mismatching-upload-offset" problem type [PROBLEM]. A server types#mismatching-upload-offset" problem type [PROBLEM]. A server
MAY use this problem type when responding to an upload append request MAY use this problem type when responding to an upload append request
(Section 6) to indicate that the "Upload-Offset" header field in the (Section 6) to indicate that the "Upload-Offset" header field in the
request does not match the upload resource's offset. request does not match the upload resource's offset.
skipping to change at page 20, line 46 skipping to change at page 21, line 15
HTTP/1.1 400 Bad Request HTTP/1.1 400 Bad Request
Content-Type: application/problem+json Content-Type: application/problem+json
{ {
"type":"https://iana.org/assignments/http-problem-types#completed-upload", "type":"https://iana.org/assignments/http-problem-types#completed-upload",
"title": "upload is already completed" "title": "upload is already completed"
} }
11. Offset values 11. Offset values
The offset of an upload resource is the number of bytes that have The offset of an upload resource is the number of bytes of the
been appended to the upload resource. Appended data cannot be representation data that have been appended to the upload resource.
removed from an upload and, therefore, the upload offset MUST NOT Appended representation data cannot be removed from an upload and,
decrease. A server MUST NOT generate responses containing an therefore, the upload offset MUST NOT decrease. A server MUST NOT
"Upload-Offset" header field with a value that is smaller than was generate responses containing an "Upload-Offset" header field with a
included in previous responses for the same upload resource. This value that is smaller than was included in previous responses for the
includes informational and final responses for upload creation same upload resource. This includes informational and final
(Section 4), upload appending (Section 6), and offset retrieval responses for upload creation (Section 4), upload appending
(Section 5). (Section 6), and offset retrieval (Section 5).
If a server loses data that has been appended to an upload, it MUST If a server loses representation data, it MUST consider the upload
consider the upload resource invalid and reject further use of the resource invalid and reject further use of the upload resource. The
upload resource. The "Upload-Offset" header field in responses "Upload-Offset" header field in responses serves as an
serves as an acknowledgement of the append operation and as a acknowledgement of the append operation and as a guarantee that no
guarantee that no retransmission of the data will be necessary. retransmission of the representation data will be necessary. Client
Client can use this guarantee to free resources associated to already can use this guarantee to free resources associated to already
uploaded data while the upload is still ongoing. uploaded representation data while the upload is still ongoing.
12. Redirection 12. Redirection
The "301 (Moved Permanently)" and "302 (Found)" status codes MUST NOT The "301 (Moved Permanently)" and "302 (Found)" status codes MUST NOT
be used in offset retrieval (Section 5) and upload cancellation be used in offset retrieval (Section 5) and upload cancellation
(Section 7) responses. For other responses, the upload resource MAY (Section 7) responses. For other responses, the upload resource MAY
return a "308 (Permanent Redirect)" status code and clients SHOULD return a "308 (Permanent Redirect)" status code and clients SHOULD
use the new permanent URI for subsequent requests. If the client use the new permanent URI for subsequent requests. If the client
receives a "307 (Temporary Redirect)" response to an offset retrieval receives a "307 (Temporary Redirect)" response to an offset retrieval
(Section 5) request, it MAY apply the redirection directly in an (Section 5) request, it MAY apply the redirection directly in an
skipping to change at page 22, line 12 skipping to change at page 22, line 27
header field cannot be used in conjunction with the "Transfer- header field cannot be used in conjunction with the "Transfer-
Encoding" header field. Encoding" header field.
15. Integrity Digests 15. 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].
15.1. Representation Digests 15.1. Representation Digests
Representation digests help verify the integrity of the entire data Representation digests help verify the integrity of the entire
that has been uploaded so far, which might strech across multiple representation data that has been uploaded so far, which might strech
requests. across multiple requests.
If the client knows the integrity digest of the entire data before If the client knows the integrity digest of the entire representation
creating an upload resource, it MAY include the "Repr-Digest" header data before creating an upload resource, it MAY include the "Repr-
field when creating an upload (Section 4). Once the upload is Digest" header field when creating an upload (Section 4). Once the
completed, the server can compute the integrity digest of the upload is completed, the server can compute the integrity digest of
received upload representation and compare it to the provided digest. the received representation data and compare it to the provided
If the digests don't match the server SHOULD consider the transfer digest. If the digests don't match, the server SHOULD consider the
failed and not process the uploaded data further. This way, the upload failed and not process the representation further. This way,
integrity of the entire uploaded data can be protected. the integrity of the entire representation data can be protected.
Alternatively, when creating an upload (Section 4), the client MAY Alternatively, when creating an upload (Section 4), the client MAY
ask the server to compute and return the integrity digests using a ask the server to compute and return the integrity digests using a
"Want-Repr-Digest" field conveying the preferred algorithms. The "Want-Repr-Digest" field conveying the preferred algorithms. The
response SHOULD include at least one of the requested digests, but response SHOULD include at least one of the requested digests, but
MAY not include it. The server SHOULD compute the representation MAY not include it. The server SHOULD compute the representation
digests using the preferred algorithms once the upload is complete digests using the preferred algorithms once the upload is complete
and include the corresponding "Repr-Digest" header field in the and include the corresponding "Repr-Digest" header field in the
response. Alternatively, the server MAY compute the digest response. Alternatively, the server MAY compute the digest
continuously during the upload and include the "Repr-Digest" header continuously during the upload and include the "Repr-Digest" header
field in responses to upload creation (Section 4) and upload field in responses to upload creation (Section 4) and upload
appending requests (Section 6) even when the upload is not completed appending requests (Section 6) even when the upload is not completed
yet. This allows the client to simultaneously compute the digest of yet. This allows the client to simultaneously compute the digest of
the transmitted upload data, compare its digest to the server's the transmitted representation data, compare its digest to the
digest, and spot data integrity issues. If an upload is spread server's digest, and spot data integrity issues. If an upload is
across multiple requests, data integrity issues can be found even spread across multiple requests, data integrity issues can be found
before the upload is fully completed. even before the upload is fully completed.
15.2. Content Digests 15.2. Content Digests
Content digests help verify the integrity of the content in an Content digests help verify the integrity of the content in an
individual request. individual request.
If the client knows the integrity digest of the content from an If the client knows the integrity digest of the content from an
upload creation (Section 4) or upload appending (Section 6) request, upload creation (Section 4) or upload appending (Section 6) request,
it MAY include the "Content-Digest" header field in the request. it MAY include the "Content-Digest" header field in the request.
Once the content has been received, the server can compute the Once the content has been received, the server can compute the
integrity digest of the received content and compare it to 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 and not append the content to the upload consider the transfer failed and not append the content to the upload
resource. This way, the integrity of an individual request can be resource. This way, the integrity of an individual request can be
protected. protected.
16. Subsequent Resources 16. Subsequent Resources
The server might process the uploaded data and make its results The server might process the uploaded representation data and make
available in another resource during or after the upload. This its results available in another resource during or after the upload.
subsequent resource is different from the upload resource created by This subsequent resource is different from the upload resource
the upload creation request (Section 4). The subsequent resource created by the upload creation request (Section 4). The subsequent
does not handle the upload process itself, but instead facilitates resource does not handle the upload process itself, but instead
further interaction with the uploaded data. The server MAY indicate facilitates further interaction with the uploaded representation
the location of this subsequent resource by including the "Content- data. The server MAY indicate the location of this subsequent
Location" header field in the informational or final responses resource by including the "Content-Location" header field in the
generated while creating (Section 4), appending to (Section 6), or informational or final responses generated while creating
retrieving the offset (Section 5) of an upload. For example, a (Section 4), appending to (Section 6), or retrieving the offset
subsequent resource could allow the client to fetch information (Section 5) of an upload. For example, a subsequent resource could
extracted from the uploaded data. allow the client to fetch information extracted from the uploaded
representation data.
17. Upload Strategies 17. Upload Strategies
The definition of the upload creation request (Section 4) provides The definition of the upload creation request (Section 4) provides
the client with flexibility to choose whether the file is fully or the client with flexibility to choose whether the representation data
partially transferred in the first request, or if no file data is is fully or partially transferred in the first request, or if no
included at all. Which behavior is best largely depends on the representation data is included at all. Which behavior is best
client's capabilities, its intention to avoid data re-transmission, largely depends on the client's capabilities, its intention to avoid
and its knowledge about the server's support for resumable uploads. data re-transmission, and its knowledge about the server's support
for resumable uploads.
The following subsections describe two typical upload strategies that The following subsections describe two typical upload strategies that
are suited for common environments. Note that these modes are never are suited for common environments. Note that these modes are never
explicitly communicated to the server and clients are not required to explicitly communicated to the server and clients are not required to
stick to one strategy, but can mix and adapt them to their needs. stick to one strategy, but can mix and adapt them to their needs.
17.1. Optimistic Upload Creation 17.1. Optimistic Upload Creation
An "optimistic upload creation" can be used independent of the An "optimistic upload creation" can be used independent of the
client's knowledge about the server's support for resumable uploads. client's knowledge about the server's support for resumable uploads.
However, the client must be capable of handling and processing However, the client must be capable of handling and processing
interim responses. An upload creation request then includes the full interim responses. An upload creation request then includes the full
file because the client anticipates that the file will be transferred representation data because the client anticipates that it will be
without interruptions or resumed if an interruption occurs. transferred without interruptions or resumed if an interruption
occurs.
The benefit of this method is that if the upload creation request The benefit of this method is that if the upload creation request
succeeds, the file was transferred in a single request without succeeds, the representation data was transferred in a single request
additional round trips. 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 received a
"104 (Upload Resumption Supported)" intermediate response with the "104 (Upload Resumption Supported)" interim response with the upload
upload URL, the client cannot resume that upload due to the missing URL, the client cannot resume that upload due to the missing upload
upload URL. The intermediate response might not be received if the URL. The interim response might not be received if the interruption
interruption happens too early in the message exchange, the server happens too early in the message exchange, the server does not
does not support resumable uploads at all, the server does not support resumable uploads at all, the server does not support sending
support sending the "104 (Upload Resumption Supported)" intermediate the "104 (Upload Resumption Supported)" interim response, or an
response, or an intermediary dropped the intermediate response. intermediary dropped the interim response. Without a 104 response,
Without a 104 response, the client needs to either treat the upload the client needs to either treat the upload as failed or retry the
as failed or retry the entire upload creation request if this is entire upload creation request if this is allowed by the application.
allowed by the application.
A client might wait for a limited duration to receive a 104 (Upload
Resumption Supported) interim response before starting to transmit
the request content. This way, the client can learn about the
resource's support for resumable uploads and/or the upload URL. This
is conceptually similar to how a client might wait for a 100
(Continue) interim response (see Section 10.1.1 of [HTTP]) before
committing to work.
17.1.1. Upgrading To Resumable Uploads 17.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 file is transferred in a single request, non-resumable upload, the representation is transferred in a single
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 offer the server to upgrade such a
request to a resumable upload (see Section 4.1) by adding the request to a resumable upload (see Section 4.1) by adding the
"Upload-Complete: ?1" header field to the original request. The "Upload-Complete: ?1" header field to the original request. The
"Upload-Length" header field SHOULD be added if the upload's final "Upload-Length" header field SHOULD be added if the upload's final
size is known upfront. The request is not changed otherwise. size is known 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
a resumable upload resource and send its upload URL in a "104 (Upload a resumable upload resource and send its upload URL in a "104 (Upload
Resumption Supported)" intermediate response for the client to resume Resumption Supported)" interim response for the client to resume the
the upload after interruptions. A server that does not support upload after interruptions. A server that does not support resumable
resumable uploads or does not want to upgrade to a resumable upload uploads or does not want to upgrade to a resumable upload for this
for this request ignores the "Upload-Complete: ?1" header. The request ignores the "Upload-Complete: ?1" header. The transfer then
transfer then falls back to a non-resumable upload without additional falls back to a non-resumable upload without additional cost.
cost.
This upgrade can also be performed transparently by the client This upgrade can also be performed transparently by the client
without the user taking an active role. When a user asks the client without the user taking an active role. When a user asks the client
to send a non-resumable request, the client can perform the upgrade to send a non-resumable request, the client can perform the upgrade
and handle potential interruptions and resumptions under the hood and handle potential interruptions and resumptions under the hood
without involving the user. The last response received by the client without involving the user. The last response received by the client
is considered the response for the entire file upload and should be is considered the response for the entire upload and should be
presented to the user. presented to the user.
17.2. Careful Upload Creation 17.2. Careful Upload Creation
For a "careful upload creation" the client knows that the server For a "careful upload creation" the client knows that the server
supports resumable uploads and sends an empty upload creation request supports resumable uploads and sends an empty upload creation request
without including any file data. Upon successful response reception, without including any representation data. Upon successful response
the client can use the included upload URL to transmit the file data reception, the client can use the included upload URL to transmit the
(Section 6) and resume the upload at any stage if an interruption representation data (Section 6) and resume the upload at any stage if
occurs. The client should inspect the response for the "Upload- an interruption occurs. The client should inspect the response for
Limit" header field, which would indicate limits applying to the the "Upload-Limit" header field, which would indicate limits applying
remaining upload procedure. to the remaining upload procedure.
The retransmission of file data or the ultimate upload failure that The retransmission of representation data or the ultimate upload
can happen with an "optimistic upload creation" is therefore avoided failure that can happen with an "optimistic upload creation" is
at the expense of an additional request that does not carry file therefore avoided at the expense of an additional request that does
data. not carry representation data.
This approach best suited if the client cannot receive intermediate This approach best suited if the client cannot receive interim
responses, e.g. due to a limitation in the provided HTTP interface, responses, e.g. due to a limitation in the provided HTTP interface,
or if large files are transferred where the cost of the additional or if large representations are transferred where the cost of the
request is miniscule compared to the effort of transferring the large additional request is miniscule compared to the effort of
file itself. transferring the representation itself.
18. Security Considerations 18. Security Considerations
The upload resource URL is the identifier used for modifying the The upload resource URL is the identifier used for modifying the
upload. Without further protection of this URL, an attacker may upload. Without further protection of this URL, an attacker may
obtain information about an upload, append data to it, or cancel it. obtain information about an upload, append data to it, or cancel it.
To prevent this, the server SHOULD ensure that only authorized To prevent this, the server SHOULD ensure that only authorized
clients can access the upload resource. In addition, the upload clients can access the upload resource. In addition, the upload
resource URL SHOULD be generated in such a way that makes it hard to resource URL SHOULD be generated in such a way that makes it hard to
be guessed by unauthorized clients. be guessed by unauthorized clients.
Some servers or intermediaries provide scanning of content uploaded Some servers or intermediaries provide scanning of content uploaded
by clients. Any scanning mechanism that relies on receiving a by clients. Any scanning mechanism that relies on receiving a
complete file in a single request message can be defeated by complete representation in a single request message can be defeated
resumable uploads because content can be split across multiple by resumable uploads because content can be split across multiple
messages. Servers or intermediaries wishing to perform content messages. Servers or intermediaries wishing to perform content
scanning SHOULD consider how resumable uploads can circumvent scanning SHOULD consider how resumable uploads can circumvent
scanning and take appropriate measures. Possible strategies include scanning and take appropriate measures. Possible strategies include
waiting for the upload to complete before scanning a full file, or waiting for the upload to complete before scanning the entire
disabling resumable uploads. representation, or disabling resumable uploads.
Resumable uploads are vulnerable to Slowloris-style attacks Resumable uploads are vulnerable to Slowloris-style attacks
[SLOWLORIS]. A malicious client may create upload resources and keep [SLOWLORIS]. A malicious client may create upload resources and keep
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. with minimal work.
Servers SHOULD provide mitigations for Slowloris attacks, such as Servers SHOULD provide mitigations for Slowloris attacks, such as
increasing the maximum number of clients the server will allow, increasing the maximum number of clients the server will allow,
skipping to change at page 28, line 14 skipping to change at page 28, line 40
20. References 20. References
20.1. Normative References 20.1. Normative References
[CACHING] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, [CACHING] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP Caching", STD 98, RFC 9111, Ed., "HTTP Caching", STD 98, RFC 9111,
DOI 10.17487/RFC9111, June 2022, DOI 10.17487/RFC9111, June 2022,
<https://www.rfc-editor.org/info/rfc9111>. <https://www.rfc-editor.org/info/rfc9111>.
[CONTENT-DISPOSITION]
Reschke, J., "Use of the Content-Disposition Header Field
in the Hypertext Transfer Protocol (HTTP)", RFC 6266,
DOI 10.17487/RFC6266, June 2011,
<https://www.rfc-editor.org/info/rfc6266>.
[DIGEST-FIELDS] [DIGEST-FIELDS]
Polli, R. and L. Pardue, "Digest Fields", RFC 9530, Polli, R. and L. Pardue, "Digest Fields", RFC 9530,
DOI 10.17487/RFC9530, February 2024, DOI 10.17487/RFC9530, February 2024,
<https://www.rfc-editor.org/info/rfc9530>. <https://www.rfc-editor.org/info/rfc9530>.
[HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, [HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP Semantics", STD 97, RFC 9110, Ed., "HTTP Semantics", STD 97, RFC 9110,
DOI 10.17487/RFC9110, June 2022, DOI 10.17487/RFC9110, June 2022,
<https://www.rfc-editor.org/info/rfc9110>. <https://www.rfc-editor.org/info/rfc9110>.
[PATCH] Dusseault, L. and J. Snell, "PATCH Method for HTTP",
RFC 5789, DOI 10.17487/RFC5789, March 2010,
<https://www.rfc-editor.org/info/rfc5789>.
[PROBLEM] Nottingham, M., Wilde, E., and S. Dalal, "Problem Details [PROBLEM] Nottingham, M., Wilde, E., and S. Dalal, "Problem Details
for HTTP APIs", RFC 9457, DOI 10.17487/RFC9457, July 2023, for HTTP APIs", RFC 9457, DOI 10.17487/RFC9457, July 2023,
<https://www.rfc-editor.org/info/rfc9457>. <https://www.rfc-editor.org/info/rfc9457>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP",
RFC 5789, DOI 10.17487/RFC5789, March 2010,
<https://www.rfc-editor.org/info/rfc5789>.
[RFC6266] Reschke, J., "Use of the Content-Disposition Header Field
in the Hypertext Transfer Protocol (HTTP)", RFC 6266,
DOI 10.17487/RFC6266, June 2011,
<https://www.rfc-editor.org/info/rfc6266>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC9112] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, [RFC9112] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP/1.1", STD 99, RFC 9112, DOI 10.17487/RFC9112, Ed., "HTTP/1.1", STD 99, RFC 9112, DOI 10.17487/RFC9112,
June 2022, <https://www.rfc-editor.org/info/rfc9112>. June 2022, <https://www.rfc-editor.org/info/rfc9112>.
[STRUCTURED-FIELDS] [STRUCTURED-FIELDS]
Nottingham, M. and P. Kamp, "Structured Field Values for Nottingham, M. and P. Kamp, "Structured Field Values for
skipping to change at page 29, line 22 skipping to change at page 29, line 48
[SLOWLORIS] [SLOWLORIS]
"RSnake" Hansen, R., "Welcome to Slowloris - the low "RSnake" Hansen, R., "Welcome to Slowloris - the low
bandwidth, yet greedy and poisonous HTTP client!", June bandwidth, yet greedy and poisonous HTTP client!", June
2009, <https://web.archive.org/web/20150315054838/ 2009, <https://web.archive.org/web/20150315054838/
http://ha.ckers.org/slowloris/>. http://ha.ckers.org/slowloris/>.
20.3. URIs 20.3. URIs
[1] https://tus.io/ [1] https://tus.io/
Appendix A. Informational Response
The server is allowed to respond to upload creation (Section 4)
requests with a "104 (Upload Resumption Supported)" intermediate
response as soon as the server has validated the request. This way,
the client knows that the server supports resumable uploads before
the complete response is received. The benefit is the clients can
defer starting the actual data transfer until the server indicates
full support (i.e. resumable are supported, the provided upload URL
is active etc).
On the contrary, support for intermediate responses (the "1XX" range)
in existing software is limited or not at all present. Such software
includes proxies, firewalls, browsers, and HTTP libraries for clients
and server. Therefore, the "104 (Upload Resumption Supported)"
status code is optional and not mandatory for the successful
completion of an upload. Otherwise, it might be impossible in some
cases to implement resumable upload servers using existing software
packages. Furthermore, as parts of the current internet
infrastructure currently have limited support for intermediate
responses, a successful delivery of a "104 (Upload Resumption
Supported)" from the server to the client should be assumed.
We hope that support for intermediate responses increases in the near
future, to allow a wider usage of "104 (Upload Resumption
Supported)".
Appendix B. Feature Detection
This specification includes a section about feature detection (it was
called service discovery in earlier discussions, but this name is
probably ill-suited). The idea is to allow resumable uploads to be
transparently implemented by HTTP clients. This means that
application developers just keep using the same API of their HTTP
library as they have done in the past with traditional, non-resumable
uploads. Once the HTTP library gets updated (e.g. because mobile OS
or browsers start implementing resumable uploads), the HTTP library
can transparently decide to use resumable uploads without explicit
configuration by the application developer. Of course, in order to
use resumable uploads, the HTTP library needs to know whether the
server supports resumable uploads. If no support is detected, the
HTTP library should use the traditional, non-resumable upload
technique. We call this process feature detection.
Ideally, the technique used for feature detection meets following
*criteria* (there might not be one approach which fits all
requirements, so we have to prioritize them):
1. Avoid additional roundtrips by the client, if possible (i.e. an
additional HTTP request by the client should be avoided).
2. Be backwards compatible to HTTP/1.1 and existing network
infrastructure: This means to avoid using new features in HTTP/2,
or features which might require changes to existing network
infrastructure (e.g. nginx or HTTP libraries)
3. Conserve the user's privacy (i.e. the feature detection should
not leak information to other third-parties about which URLs have
been connected to)
Following *approaches* have already been considered in the past. All
except the last approaches have not been deemed acceptable and are
therefore not included in the specification. This follow list is a
reference for the advantages and disadvantages of some approaches:
*Include a support statement in the SETTINGS frame.* The SETTINGS
frame is a HTTP/2 feature and is sent by the server to the client to
exchange information about the current connection. The idea was to
include an additional statement in this frame, so the client can
detect support for resumable uploads without an additional roundtrip.
The problem is that this is not compatible with HTTP/1.1.
Furthermore, the SETTINGS frame is intended for information about the
current connection (not bound to a request/response) and might not be
persisted when transmitted through a proxy.
*Include a support statement in the DNS record.* The client can
detect support when resolving a domain name. Of course, DNS is not
semantically the correct layer. Also, DNS might not be involved if
the record is cached or retrieved from a hosts files.
*Send a HTTP request to ask for support.* This is the easiest
approach where the client sends an OPTIONS request and uses the
response to determine if the server indicates support for resumable
uploads. An alternative is that the client sends the request to a
well-known URL to obtain this response, e.g. "/.well-known/resumable-
uploads". Of course, while being fully backwards-compatible, it
requires an additional roundtrip.
*Include a support statement in previous responses.* In many cases,
the file upload is not the first time that the client connects to the
server. Often additional requests are sent beforehand for
authentication, data retrieval etc. The responses for those requests
can also include a header field which indicates support for resumable
uploads. There are two options: - Use the standardized "Alt-Svc"
response header field. However, it has been indicated to us that
this header field might be reworked in the future and could also be
semantically different from our intended usage. - Use a new response
header field "Resumable-Uploads: https://example.org/files/*" to
indicate under which endpoints support for resumable uploads is
available.
*Send a 104 intermediate response to indicate support.* The clients
normally starts a traditional upload and includes a header field
indicate that it supports resumable uploads (e.g. "Upload-Offset:
0"). If the server also supports resumable uploads, it will
immediately respond with a 104 intermediate response to indicate its
support, before further processing the request. This way the client
is informed during the upload whether it can resume from possible
connection errors or not. While an additional roundtrip is avoided,
the problem with that solution is that many HTTP server libraries do
not support sending custom 1XX responses and that some proxies may
not be able to handle new 1XX status codes correctly.
*Send a 103 Early Hint response to indicate support.* This approach
is the similar to the above one, with one exception: Instead of a new
"104 (Upload Resumption Supported)" status code, the existing "103
(Early Hint)" status code is used in the intermediate response. The
103 code would then be accompanied by a header field indicating
support for resumable uploads (e.g. "Resumable-Uploads: 1"). It is
unclear whether the Early Hints code is appropriate for that, as it
is currently only used to indicate resources for prefetching them.
Appendix C. Upload Metadata
When an upload is created (Section 4), the "Content-Type" and
"Content-Disposition" header fields are allowed to be included. They
are intended to be a standardized way of communicating the file name
and file type, if available. However, this is not without
controversy. Some argue that since these header fields are already
defined in other specifications, it is not necessary to include them
here again. Furthermore, the "Content-Disposition" header field's
format is not clearly enough defined. For example, it is left open
which disposition value should be used in the header field. There
needs to be more discussion whether this approach is suited or not.
However, from experience with the tus project, users are often asking
for a way to communicate the file name and file type. Therefore, we
believe it is help to explicitly include an approach for doing so.
Appendix D. FAQ
o *Are multipart requests supported?* Yes, requests whose content is
encoded using the "multipart/form-data" are implicitly supported.
The entire encoded content can be considered as a single file,
which is then uploaded using the resumable protocol. The server,
of course, must store the delimiter ("boundary") separating each
part and must be able to parse the multipart format once the
upload is completed.
Acknowledgments Acknowledgments
This document is based on an Internet-Draft specification written by This document is based on an Internet-Draft specification written by
Jiten Mehta, Stefan Matsson, and the authors of this document. Jiten Mehta, Stefan Matsson, and the authors of this document.
The tus v1 protocol [1] is a specification for a resumable file The tus v1 protocol [1] is a specification for a resumable file
upload protocol over HTTP. It inspired the early design of this upload protocol over HTTP. It inspired the early design of this
protocol. Members of the tus community helped significantly in the protocol. Members of the tus community helped significantly in the
process of bringing this work to the IETF. process of bringing this work to the IETF.
The authors would like to thank Mark Nottingham for substantive The authors would like to thank Mark Nottingham for substantive
contributions to the text. contributions to the text.
Changes Changes
This section is to be removed before publishing as an RFC. This section is to be removed before publishing as an RFC.
F.1. Since draft-ietf-httpbis-resumable-upload-04 B.1. Since draft-ietf-httpbis-resumable-upload-05
o Reduce use of "file" in favor of "representation".
B.2. 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".
F.2. Since draft-ietf-httpbis-resumable-upload-03 B.3. 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.
F.3. Since draft-ietf-httpbis-resumable-upload-02 B.4. 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.
F.4. Since draft-ietf-httpbis-resumable-upload-01 B.5. 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.
F.5. Since draft-ietf-httpbis-resumable-upload-00 B.6. 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.
F.6. Since draft-tus-httpbis-resumable-uploads-protocol-02 B.7. Since draft-tus-httpbis-resumable-uploads-protocol-02
None None
F.7. Since draft-tus-httpbis-resumable-uploads-protocol-01 B.8. 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.
F.8. Since draft-tus-httpbis-resumable-uploads-protocol-00 B.9. 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.
Authors' Addresses Authors' Addresses
Marius Kleidl (editor) Marius Kleidl (editor)
Transloadit Transloadit
Email: marius@transloadit.com Email: marius@transloadit.com
 End of changes. 84 change blocks. 
423 lines changed or deleted 299 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/