draft-ietf-httpbis-resumable-upload-01.txt   draft-ietf-httpbis-resumable-upload-latest.txt 
HTTP Working Group M. Kleidl, Ed. HTTP Working Group M. Kleidl, Ed.
Internet-Draft Transloadit Ltd Internet-Draft Transloadit Ltd
Intended status: Standards Track G. Zhang, Ed. Intended status: Standards Track G. Zhang, Ed.
Expires: September 3, 2023 Apple Inc. Expires: March 15, 2024 Apple Inc.
L. Pardue, Ed. L. Pardue, Ed.
Cloudflare Cloudflare
March 02, 2023 September 12, 2023
Resumable Uploads for HTTP Resumable Uploads for HTTP
draft-ietf-httpbis-resumable-upload-01 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 data transfer of the entire representation, it is often desirable to
issue subsequent requests that transfer only the remainder of the issue 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
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 September 3, 2023. This Internet-Draft will expire on March 15, 2024.
Copyright Notice Copyright Notice
Copyright (c) 2023 IETF Trust and the persons identified as the Copyright (c) 2023 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. Uploading Overview . . . . . . . . . . . . . . . . . . . . . 4 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 4
3.1. Example 1: Complete upload of file with known size . . . 4 3.1. Example 1: Complete upload of file with known size . . . 4
3.2. Example 2: Upload as a series of parts . . . . . . . . . 7 3.2. Example 2: Upload as a series of parts . . . . . . . . . 6
4. Upload Creation Procedure . . . . . . . . . . . . . . . . . . 8 4. Upload Creation . . . . . . . . . . . . . . . . . . . . . . . 7
4.1. Feature Detection . . . . . . . . . . . . . . . . . . . . 10 4.1. Feature Detection . . . . . . . . . . . . . . . . . . . . 10
4.2. Draft Version Identification . . . . . . . . . . . . . . 10 4.2. Draft Version Identification . . . . . . . . . . . . . . 10
5. Offset Retrieving Procedure . . . . . . . . . . . . . . . . . 11 5. Offset Retrieval . . . . . . . . . . . . . . . . . . . . . . 11
6. Upload Appending Procedure . . . . . . . . . . . . . . . . . 12 6. Upload Append . . . . . . . . . . . . . . . . . . . . . . . . 12
7. Upload Cancellation Procedure . . . . . . . . . . . . . . . . 14 7. Upload Cancellation . . . . . . . . . . . . . . . . . . . . . 14
8. Request Identification . . . . . . . . . . . . . . . . . . . 15 8. Header Fields . . . . . . . . . . . . . . . . . . . . . . . . 15
9. Header Fields . . . . . . . . . . . . . . . . . . . . . . . . 15 8.1. Upload-Offset . . . . . . . . . . . . . . . . . . . . . . 15
9.1. Upload-Offset . . . . . . . . . . . . . . . . . . . . . . 15 8.2. Upload-Complete . . . . . . . . . . . . . . . . . . . . . 15
9.2. Upload-Incomplete . . . . . . . . . . . . . . . . . . . . 15 9. Redirection . . . . . . . . . . . . . . . . . . . . . . . . . 15
10. Redirection . . . . . . . . . . . . . . . . . . . . . . . . . 16 10. Security Considerations . . . . . . . . . . . . . . . . . . . 15
11. Security Considerations . . . . . . . . . . . . . . . . . . . 16 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16
12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 12. Normative References . . . . . . . . . . . . . . . . . . . . 16
13. Normative References . . . . . . . . . . . . . . . . . . . . 17 Appendix A. Since draft-ietf-httpbis-resumable-upload-01 . . . . 17
Appendix A. Since draft-ietf-httpbis-resumable-upload-00 . . . . 17 A.1. Since draft-ietf-httpbis-resumable-upload-00 . . . . . . 17
A.1. Since draft-tus-httpbis-resumable-uploads-protocol-02 . . 18 A.2. Since draft-tus-httpbis-resumable-uploads-protocol-02 . . 17
A.2. Since draft-tus-httpbis-resumable-uploads-protocol-01 . . 18 A.3. Since draft-tus-httpbis-resumable-uploads-protocol-01 . . 17
A.3. Since draft-tus-httpbis-resumable-uploads-protocol-00 . . 18 A.4. Since draft-tus-httpbis-resumable-uploads-protocol-00 . . 17
Appendix B. Informational Response . . . . . . . . . . . . . . . 18 Appendix B. Informational Response . . . . . . . . . . . . . . . 17
Appendix C. Feature Detection . . . . . . . . . . . . . . . . . 19 Appendix C. Feature Detection . . . . . . . . . . . . . . . . . 18
Appendix D. Upload Metadata . . . . . . . . . . . . . . . . . . 21 Appendix D. Upload Metadata . . . . . . . . . . . . . . . . . . 20
Appendix E. FAQ . . . . . . . . . . . . . . . . . . . . . . . . 21 Appendix E. FAQ . . . . . . . . . . . . . . . . . . . . . . . . 20
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 21 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 21
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21
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 data transfer of the entire
representation, it is often desirable to issue subsequent requests representation, it is often desirable to issue subsequent requests
skipping to change at page 3, line 44 skipping to change at page 3, line 44
process of sending additional parts of a representation using 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 the Resumable Uploads Protocol, an optional This document defines an optional mechanism for HTTP than enables
mechanism for resumable uploads using HTTP that is backwards- resumable uploads in a way that is backwards-compatible with
compatible with conventional HTTP uploads. When an upload is conventional HTTP uploads. When an upload is interrupted, clients
interrupted, clients can send subsequent requests to query the server can send subsequent requests to query the server state and use this
state and use this information to the send remaining data. information to the send remaining data. Alternatively, they can
Alternatively, they can cancel the upload entirely. Different from cancel the upload entirely. Different from ranged downloads, this
ranged downloads, this protocol does not support transferring protocol does not support transferring different parts of the same
different parts of the same representation in parallel. 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, sf-binary, sf-boolean, sf- The terms Byte Sequence, Item, String, Token, Integer, and Boolean
integer, sf-string, and sf-token are imported from are imported from [STRUCTURED-FIELDS].
[STRUCTURED-FIELDS].
The terms client and server are imported from [HTTP].
Upload: A sequence of one or more procedures, uniquely identified by
an upload URL chosen by a server.
Procedure: An HTTP message exchange for that can be used for
resumable uploads.
3. Uploading Overview
The Resumable Uploads Protocol consists of several procedures that
rely on HTTP message exchanges. The following procedures are
defined:
o Upload Creation Procedure (Section 4)
o Offset Retrieving Procedure (Section 5)
o Upload Appending Procedure (Section 6) The terms client and server are from [HTTP].
o Upload Cancellation Procedure (Section 7) 3. Overview
A single upload is a sequence of one or more procedures. Each upload Resumable uploads are supported in HTTP through use of a temporary
is uniquely identified by an upload URL chosen by a server. resource, an _upload resource_, that is separate from the resource
being uploaded to (hereafter, the _target resource_) and specific to
that upload. By interacting with the upload resource, a client can
retrieve the current offset of the upload (Section 5), append to the
upload (Section 6), and cancel the upload (Section 7).
The remainder of this section uses examples of a file upload to The remainder of this section uses an example of a file upload to
illustrate permutations of procedure sequence. Note, however, that illustrate different interactions with the upload resource. Note,
HTTP message exchanges use representation data (see Section 8.1 of however, that HTTP message exchanges use representation data (see
[HTTP]), which means that procedures can apply to many forms of Section 8.1 of [HTTP]), which means that resumable uploads can used
content. with many forms of content -- not just static files.
3.1. Example 1: Complete upload of file with known size 3.1. Example 1: Complete upload of file 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 a file with a
known size in a single HTTP request. An interruption occurs and the known size in a single HTTP request to the target resource. An
client then attempts to resume the upload using subsequent HTTP interruption occurs and the client then attempts to resume the upload
requests. using subsequent HTTP requests to the upload resource.
1) The Upload Creation Procedure (Section 4) can be used to notify 1) The client notifies the server that it wants to begin an upload
the server that the client wants to begin an upload. The server (Section 4). The server reserves the required resources to accept
should then reserve the required resources to accept the upload from the upload from the client, and the client begins transferring the
the client. The client also begins transferring the entire file in entire file in the request content.
the request body. An informational response can be sent to the
client to signal the support of resumable upload on the server and An informational response can be sent to the client to signal the
transmit the upload URL in the Location header, which is used for support of resumable upload on the server and transmit the upload
identifying future requests related to this upload. resource URL in the Location header.
Client Server Client Server
| | | |
| POST | | POST |
|------------------------------------------->| |------------------------------------------->|
| | | |
| | Reserve resources | | Reserve resources
| | for upload | | for upload
| |------------------ | |------------------
| | | | | |
| |<----------------- | |<-----------------
| | | |
| 104 Upload Resumption Supported | | 104 Upload Resumption Supported |
| with upload URL | | with upload resouce URL |
|<-------------------------------------------| |<-------------------------------------------|
| | | |
| Flow Interrupted | | Flow Interrupted |
|------------------------------------------->| |------------------------------------------->|
| | | |
Figure 1: Upload Creation Procedure Figure 1: Upload Creation
2) If the connection to the server gets interrupted during the Upload 2) If the connection to the server gets interrupted, the client may
Creation Procedure, the client may want to resume the upload. Before want to resume the upload. Before this is possible, the client must
this is possible, the client must know the amount of data that the know the amount of data that the server was able to receive before
server was able to receive before the connection got interrupted. To the connection got interrupted. To achieve this, the client
achieve this, the client uses the Offset Retrieving Procedure retrieves the offset (Section 5) from the upload resource.
(Section 5) to obtain the upload's offset using the upload URL.
Client Server Client Server
| | | |
| HEAD to upload URL | | HEAD to upload resource URL |
|----------------------------------------------->| |----------------------------------------------->|
| | | |
| 204 No Content with Upload-Offset | | 204 No Content with Upload-Offset |
|<-----------------------------------------------| |<-----------------------------------------------|
| | | |
Figure 2: Offset Retrieving Procedure Figure 2: Offset Retrieval
3) After the Offset Retrieving Procedure (Section 5) completes, the 3) Afterwards, the client can resume the upload by sending the
client can resume the upload by sending the remaining file content to remaining file content to the upload resource (Section 6), appending
the server using the Upload Appending Procedure (Section 6), to the already stored data in the upload. The "Upload-Offset" value
appending to the already stored data in the upload. The "Upload- is included to ensure that the client and server agree on the offset
Offset" value is included to ensure that the client and server agree that the upload resumes from.
on the offset that the upload resumes from.
Client Server Client Server
| | | |
| PATCH to upload URL with Upload-Offset | | PATCH to upload resource URL with Upload-Offset |
|----------------------------------------------->| |------------------------------------------------>|
| | | |
| 201 Created on completion | | 201 Created on completion |
|<-----------------------------------------------| |<------------------------------------------------|
| | | |
Figure 3: Upload Appending Procedure Figure 3: Upload Append
4) If the client is not interested in completing the upload anymore, 4) If the client is not interested in completing the upload anymore,
it can instruct the server to delete the upload and free all related it can instruct the upload resource to delete the upload and free all
resources using the Upload Cancellation Procedure (Section 7). related resources (Section 7).
Client Server Client Server
| | | |
| DELETE to upload URL | | DELETE to upload resource URL |
|----------------------------------------------->| |----------------------------------------------->|
| | | |
| 204 No Content on completion | | 204 No Content on completion |
|<-----------------------------------------------| |<-----------------------------------------------|
| | | |
Figure 4: Upload Cancellation Procedure 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 file as a series of
parts sent across multiple HTTP messages. One use case is to parts sent serially across multiple HTTP messages. One use case is
overcome server limits on HTTP message content size. Another use to overcome server limits on HTTP message content size. Another use
case is where the client does not know the final size, such as when case is where the client does not know the final size, such as when
file data originates from a streaming source. file 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 over a server's resumable upload support, can upload parts of a file
sequence of procedures. 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 use the Upload Creation Procedure with the "Upload-Incomplete" it can start an upload with the "Upload-Complete: ?0" and the first
header to start an upload. The client can include the first part of part of the file.
the file in the Upload Creation Procedure.
Client Server Client Server
| | | |
| POST with Upload-Incomplete | | POST with Upload-Complete: ?0 |
|----------------------------------------------->| |----------------------------------------------->|
| | | |
| 201 Created with Upload-Incomplete | | 201 Created with Upload-Complete: ?0 |
| and Location on completion | | and Location on completion |
|<-----------------------------------------------| |<-----------------------------------------------|
| | | |
Figure 5: Upload Creation Procedure Incomplete Figure 5: Incomplete Upload Creation
2) After creation, the following parts are sent using the Upload 2) Afterwards, the following parts are appended (Section 6), and the
Appending Procedure (Section 6), and the last part of the upload does last part of the upload has the "Upload-Complete: ?1" header to
not have the "Upload-Incomplete" header. indicate the complete transfer.
Client Server Client Server
| | | |
| PATCH to upload URL and Upload-Offset | | PATCH to upload resource URL with |
| Upload-Offset and Upload-Complete: ?1 |
|----------------------------------------------->| |----------------------------------------------->|
| | | |
| 201 Created on completion | | 201 Created on completion |
|<-----------------------------------------------| |<-----------------------------------------------|
| | | |
Figure 6: Upload Appending Procedure Last Chunk Figure 6: Upload Append Last Chunk
4. Upload Creation Procedure 4. Upload Creation
The Upload Creation Procedure is intended for starting a new upload. When a resource supports resumable uploads, the first step is
A limited form of this procedure MAY be used by the client without creating the upload resource. To be compatible with the widest range
the knowledge of server support of the Resumable Uploads Protocol. of resources, this is accomplished by adding a header field to the
request that initiates the upload, "Upload-Complete".
This procedure is designed to be compatible with a regular upload. As a consequence, resumable uploads support all HTTP request methods
Therefore all methods are allowed with the exception of "GET", that can carry content, such as "POST", "PUT", and "PATCH".
"HEAD", "DELETE", and "OPTIONS". All response status codes are Similarly, the response to the upload request can have any response
allowed. The client is RECOMMENDED to use the "POST" method if not status code. Both the method(s) and status code(s) supported are
otherwise intended. The server MAY only support a limited number of determined by the resource.
methods.
The request MUST include the "Upload-Incomplete" header field "Upload-Complete" MUST be set to false if the end of the request
(Section 9.2). It MUST be set to true if the end of the request body content is not the end of the upload. Otherwise, it MUST be set to
is not the end of the upload. Otherwise, it MUST be set to false. true. This header field can be used for request identification by a
This header field can be used for request identification by a server. server. The request MUST NOT include the "Upload-Offset" header.
The request MUST NOT include the "Upload-Offset" header.
If the request is valid, the server SHOULD create an upload resource. If the request is valid, the server SHOULD create an upload resource.
If so, the server MUST include the "Location" header in the response Then, the server MUST include the "Location" header in the response
and set to the upload URL, which points to the created upload and set its value to the URL of the upload resource. The client MAY
resource. The client MAY use this upload URL to execute the Offset use this URL for offset retrieval (Section 5), upload append
Retrieving Procedure (Section 5), Upload Appending Procedure (Section 6), and upload cancellation (Section 7).
(Section 6), or Upload Cancellation Procedure (Section 7).
As soon as the upload resource is available, the server MAY send an Once the upload resource is available, the target resource MAY send
informational response with "104 (Upload Resumption Supported)" an informational response with "104 (Upload Resumption Supported)"
status to the client while the request body is being uploaded. In status to the client while the request content is being uploaded. In
this informational response, the "Location" header field MUST be set this informational response, the "Location" header field MUST be set
to the upload URL. to the upload resource.
The server MUST send the "Upload-Offset" header in the response if it The server MUST send the "Upload-Offset" header in the response if it
considers the upload active, either when the response is a success considers the upload active, either when the response is a success
(e.g. "201 (Created)"), or when the response is a failure (e.g. "409 (e.g. "201 (Created)"), or when the response is a failure (e.g. "409
(Conflict)"). The value MUST be equal to the end offset of the (Conflict)"). The value MUST be equal to the end offset of the
entire upload, or the begin offset of the next chunk if the upload is entire upload, or the begin offset of the next chunk if the upload is
still incomplete. The client SHOULD consider the upload failed if still incomplete. The client SHOULD consider the upload failed if
the response status code indicates a success but the offset in the the response status code indicates a success but the offset in the
"Upload-Offset" header field in the response does not equal to the "Upload-Offset" header field in the response does not equal to the
begin offset plus the number of bytes uploaded in the request. begin offset plus the number of bytes uploaded in the request.
If the request completes successfully and the entire upload is If the request completes successfully and the entire upload is
complete, the server MUST acknowledge it by responding with a complete, the server MUST acknowledge it by responding with a
successful status code between 200 and 299 (inclusive). Server is successful status code between 200 and 299 (inclusive). Server is
RECOMMENDED to use "201 (Created)" response if not otherwise RECOMMENDED to use "201 (Created)" response if not otherwise
specified. The response MUST NOT include the "Upload-Incomplete" specified. The response MUST NOT include the "Upload-Complete"
header with the value of true. header with the value of false.
If the request completes successfully but the entire upload is not If the request completes successfully but the entire upload is not
yet complete indicated by the "Upload-Incomplete" header, the server yet complete indicated by the "Upload-Complete: ?0" header, the
MUST acknowledge it by responding with the "201 (Created)" status server MUST acknowledge it by responding with the "201 (Created)"
code, the "Upload-Incomplete" header set to true. status code, the "Upload-Complete" header set to false.
If the request includes the "Upload-Complete: ?1" header field and a
valid "Content-Length" header field, the client attempts to upload a
fixed-length resource in one request. In this case, the upload's
final size is the value of the "Content-Length" header field and the
server MUST record the upload's final size to ensure its consistency.
:method: POST :method: POST
:scheme: https :scheme: https
:authority: example.com :authority: example.com
:path: /upload :path: /upload
upload-draft-interop-version: 3 upload-draft-interop-version: 3
upload-incomplete: ?0 upload-complete: ?1
content-length: 100 content-length: 100
[content (100 bytes)] [content (100 bytes)]
:status: 104 :status: 104
upload-draft-interop-version: 3 upload-draft-interop-version: 3
location: https://example.com/upload/b530ce8ff location: https://example.com/upload/b530ce8ff
:status: 201 :status: 201
location: https://example.com/upload/b530ce8ff location: https://example.com/upload/b530ce8ff
upload-offset: 100 upload-offset: 100
:method: POST :method: POST
:scheme: https :scheme: https
:authority: example.com :authority: example.com
:path: /upload :path: /upload
upload-draft-interop-version: 3 upload-draft-interop-version: 3
upload-incomplete: ?1 upload-complete: ?0
content-length: 25 content-length: 25
[partial content (25 bytes)] [partial content (25 bytes)]
:status: 201 :status: 201
location: https://example.com/upload/b530ce8ff location: https://example.com/upload/b530ce8ff
upload-incomplete: ?1 upload-complete: ?0
upload-offset: 25 upload-offset: 25
If the client received an informational repsonse with the upload URL, If the client received an informational response with the upload URL,
it MAY automatically attempt upload resumption when the connection is it MAY automatically attempt upload resumption when the connection is
terminated unexpectedly, or if a server error status code between 500 terminated unexpectedly, or if a server error status code between 500
and 599 (inclusive) is received. The client SHOULD NOT automatically and 599 (inclusive) is received. The client SHOULD NOT automatically
retry if a client error status code between 400 and 499 (inclusive) retry if a client error status code between 400 and 499 (inclusive)
is received. is received.
File metadata can affect how servers might act on the uploaded file. File metadata can affect how servers might act on the uploaded file.
Clients can send Representation Metadata (see Section 8.3 of [HTTP]) Clients can send representation metadata (see Section 8.3 of [HTTP])
in the Upload Creation Procedure request that starts an upload. in the request that starts an upload. Servers MAY interpret this
Servers MAY interpret this metadata or MAY ignore it. The "Content- metadata or MAY ignore it. The "Content-Type" header can be used to
Type" header can be used to indicate the MIME type of the file. The indicate the MIME type of the file. The "Content-Disposition" header
"Content-Disposition" header can be used to transmit a filename. If can be used to transmit a filename. If included, the parameters
included, the parameters SHOULD be either "filename", "filename*" or SHOULD be either "filename", "filename*" or "boundary".
"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, the Upload Creation Procedure MAY be used with resumable uploads, a resumable request can be used with some
some additional constraints. In particular, the "Upload-Incomplete" additional constraints. In particular, the "Upload-Complete" header
header field (Section 9.2) MUST NOT be set to true if the server field (Section 8.2) MUST NOT be set to false if the server support is
support is unclear. This allows the upload to function as if it is a unclear. This allows the upload to function as if it is a regular
regular upload. upload.
The server SHOULD send the "104 (Upload Resumption Supported)" The server SHOULD send the "104 (Upload Resumption Supported)"
informational response to the client, to indicate its support for a informational response to the client, to indicate its support for a
resumable upload. resumable upload.
The client MUST NOT attempt to resume an upload if it did not receive The client MUST NOT attempt to resume an upload if it did not receive
the "104 (Upload Resumption Supported)" informational response, and the "104 (Upload Resumption Supported)" informational response, and
it does not have other signals of whether the server supporting it does not have other signals of whether the server supports
resumable upload. resumable uploads.
4.2. Draft Version Identification 4.2. Draft Version Identification
*RFC Editor's Note:* Please remove this section and "Upload-Draft- *RFC Editor's Note:* Please remove this section and "Upload-Draft-
Interop-Version" from all examples prior to publication of a final Interop-Version" from all examples prior to publication of a final
version of this document. version of this document.
The current interop version is 3. The current interop version is 3.
Client implementations of draft versions of the protocol MUST send a Client implementations of draft versions of the protocol MUST send a
skipping to change at page 11, line 16 skipping to change at page 11, line 11
a "104 (Upload Resumption Supported)" informational response with a "104 (Upload Resumption Supported)" informational response with
missing or mismatching interop version indicated by the "Upload- missing or mismatching interop version indicated by the "Upload-
Draft-Interop-Version" header field. Draft-Interop-Version" header field.
The reason both the client and the server are sending and checking The reason both the client and the server are sending and checking
the draft version is to ensure that implementations of the final RFC the draft version is to ensure that implementations of the final RFC
will not accidentally interop with draft implementations, as they will not accidentally interop with draft implementations, as they
will not check the existence of the "Upload-Draft-Interop-Version" will not check the existence of the "Upload-Draft-Interop-Version"
header field. header field.
5. Offset Retrieving Procedure 5. Offset Retrieval
If an upload is interrupted, the client MAY attempt to fetch the If an upload is interrupted, the client MAY attempt to fetch the
offset of the incomplete upload by sending a "HEAD" request to the offset of the incomplete upload by sending a "HEAD" request to the
upload URL, as obtained from the Upload Creation Procedure upload resource.
(Section 4). The client MUST NOT initiate this procedure without the
knowledge of server support.
The request MUST NOT include the "Upload-Offset" header or the The request MUST NOT include the "Upload-Offset" header or the
"Upload-Incomplete" header. The server MUST reject the request with "Upload-Complete" header. The server MUST reject the request with
the "Upload-Offset" header or the "Upload-Incomplete" header by the "Upload-Offset" header or the "Upload-Complete" header by sending
sending a "400 (Bad Request)" response. a "400 (Bad Request)" response.
If the server considers the upload associated with this upload URL If the server considers the upload resource to be active, it MUST
active, it MUST send back a "204 (No Content)" response. The send back a "204 (No Content)" response. The response MUST include
response MUST include the "Upload-Offset" header set to the current the "Upload-Offset" header set to the current resumption offset for
resumption offset for the client. The response MUST include the the target resource. The response MUST include the "Upload-Complete"
"Upload-Incomplete" header which is set to true if and only if the header which is set to true if and only if the upload is complete.
upload is incomplete. An upload is considered complete if and only
if the server completely and successfully received a corresponding
Upload Creation Procedure (Section 4) or Upload Appending Procedure
(Section 6) request with the "Upload-Incomplete" header being omitted
or set to false.
The client MUST NOT perform the Offset Retrieving Procedure An upload is considered complete only if the server completely and
(Section 5) while the Upload Creation Procedure (Section 4) or the successfully received a corresponding creation (Section 4) request or
Upload Appending Procedure (Section 6) is in progress. append (Section 6) request with the "Upload-Complete" header being
set to true.
The offset MUST be accepted by a subsequent Upload Appending The client MUST NOT perform offset retrieval while creation
Procedure (Section 6). Due to network delay and reordering, the (Section 4) or append (Section 6) is in progress.
server might still be receiving data from an ongoing transfer for the
same upload URL, which in the client perspective has failed. The
server MAY terminate any transfers for the same upload URL before
sending the response by abruptly terminating the HTTP connection or
stream. Alternatively, the server MAY keep the ongoing transfer
alive but ignore further bytes received past the offset.
The client MUST NOT start more than one Upload Appending Procedures The offset MUST be accepted by a subsequent append (Section 6). Due
(Section 6) based on the resumption offset from a single Offset to network delay and reordering, the server might still be receiving
Retrieving Procedure (Section 5). data from an ongoing transfer for the same upload resource, which in
the client perspective has failed. The server MAY terminate any
transfers for the same upload resource before sending the response by
abruptly terminating the HTTP connection or stream. Alternatively,
the server MAY keep the ongoing transfer alive but ignore further
bytes received past the offset.
The client MUST NOT start more than one append (Section 6) based on
the resumption offset from a single offset retrieving (Section 5)
request.
The response SHOULD include "Cache-Control: no-store" header to The response SHOULD include "Cache-Control: no-store" header to
prevent HTTP caching. prevent HTTP caching.
If the server does not consider the upload associated with this If the server does not consider the upload resource to be active, it
upload URL active, it MUST respond with "404 (Not Found)" status MUST respond with "404 (Not Found)" status code.
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 the client has already sent. The client MAY reject an offset
which is greater than the number of bytes it has already sent during which is greater than the number of bytes it has already sent during
this upload. The client is expected to handle backtracking of a this upload. The client is expected to handle backtracking of a
reasonable length. If the offset is invalid for this upload, or if reasonable length. If the offset is invalid for this upload, or if
the client cannot backtrack to the offset and reproduce the same the client cannot backtrack to the offset and reproduce the same
content it has already sent, the upload MUST be considered a failure. content it has already sent, the upload MUST be considered a failure.
The client MAY use the Upload Cancellation Procedure (Section 7) to The client MAY cancel the upload (Section 7) after rejecting the
cancel the upload after rejecting the offset. offset.
:method: HEAD :method: HEAD
:scheme: https :scheme: https
:authority: example.com :authority: example.com
:path: /upload/b530ce8ff :path: /upload/b530ce8ff
upload-draft-interop-version: 3 upload-draft-interop-version: 3
:status: 204 :status: 204
upload-offset: 100 upload-offset: 100
upload-incomplete: ?1 upload-complete: ?0
cache-control: no-store cache-control: no-store
The client SHOULD NOT automatically retry if a client error status The client SHOULD NOT automatically retry if a client error status
code between 400 and 499 (inclusive) is received. code between 400 and 499 (inclusive) is received.
6. Upload Appending Procedure 6. Upload Append
The Upload Appending Procedure is used for resuming an existing Upload appending is used for resuming an existing upload.
upload.
The request MUST use the "PATCH" method and be sent to the upload The request MUST use the "PATCH" method and be sent to the upload
URL, as obtained from the Upload Creation Procedure (Section 4). The resource. The "Upload-Offset" header field (Section 8.1) MUST be set
"Upload-Offset" header field (Section 9.1) MUST be set to the to the resumption offset.
resumption offset.
If the end of the request body is not the end of the upload, the If the end of the request content is not the end of the upload, the
"Upload-Incomplete" header field (Section 9.2) MUST be set to true. "Upload-Complete" header field (Section 8.2) MUST be set to false.
The server SHOULD respect representation metadata received in the The server SHOULD respect representation metadata received during
Upload Creation Procedure (Section 4) and ignore any representation creation (Section 4) and ignore any representation metadata received
metadata received in the Upload Appending Procedure (Section 6). from appending (Section 6).
If the server does not consider the upload associated with the upload If the server does not consider the upload associated with the upload
URL active, it MUST respond with "404 (Not Found)" status code. resource active, it MUST respond with "404 (Not Found)" status code.
The client MUST NOT perform multiple upload transfers for the same The client MUST NOT perform multiple upload transfers for the same
upload URL using Upload Creation Procedures (Section 4) or Upload upload resource in parallel to avoid race conditions and data loss or
Appending Procedures (Section 6) in parallel to avoid race conditions corruption. The server is RECOMMENDED to take measures to avoid
and data loss or corruption. The server is RECOMMENDED to take parallel upload transfers: The server MAY terminate any creation
measures to avoid parallel upload transfers: The server MAY terminate (Section 4) or append (Section 6) for the same upload URL. Since the
any ongoing Upload Creation Procedure (Section 4) or Upload Appending client is not allowed to perform multiple transfers in parallel, the
Procedure (Section 6) for the same upload URL. Since the client is server can assume that the previous attempt has already failed.
not allowed to perform multiple transfers in parallel, the server can Therefore, the server MAY abruptly terminate the previous HTTP
assume that the previous attempt has already failed. Therefore, the connection or stream.
server MAY abruptly terminate the previous HTTP connection or stream.
If the offset in the "Upload-Offset" header field does not match the If the offset in the "Upload-Offset" header field does not match the
offset provided by the immediate previous Offset Retrieving Procedure offset provided by the immediate previous offset retrieval
(Section 5), or the end offset of the immediate previous incomplete (Section 5), or the end offset of the immediate previous incomplete
successful transfer, the server MUST respond with "409 (Conflict)" successful transfer, the server MUST respond with "409 (Conflict)"
status code. status code.
The server MUST send the "Upload-Offset" header in the response if it The server MUST send the "Upload-Offset" header in the response if it
considers the upload active, either when the response is a success considers the upload active, either when the response is a success
(e.g. "201 (Created)"), or when the response is a failure (e.g. "409 (e.g. "201 (Created)"), or when the response is a failure (e.g. "409
(Conflict)"). The value MUST be equal to the end offset of the (Conflict)"). The value MUST be equal to the end offset of the
entire upload, or the begin offset of the next chunk if the upload is entire upload, or the begin offset of the next chunk if the upload is
still incomplete. The client SHOULD consider the upload failed if still incomplete. The client SHOULD consider the upload failed if
the response status code indicates a success but the offset in the the response status code indicates a success but the offset in the
"Upload-Offset" header field in the response does not equal to the "Upload-Offset" header field in the response does not equal to the
begin offset plus the number of bytes uploaded in the request. begin offset plus the number of bytes uploaded in the request.
If the request completes successfully and the entire upload is If the request completes successfully and the entire upload is
complete, the server MUST acknowledge it by responding with a complete, the server MUST acknowledge it by responding with a
successful status code between 200 and 299 (inclusive). Server is successful status code between 200 and 299 (inclusive). Server is
RECOMMENDED to use "201 (Created)" response if not otherwise RECOMMENDED to use "201 (Created)" response if not otherwise
specified. The response MUST NOT include the "Upload-Incomplete" specified. The response MUST NOT include the "Upload-Complete"
header with the value of true. header with the value of false.
If the request completes successfully but the entire upload is not If the request completes successfully but the entire upload is not
yet complete indicated by the "Upload-Incomplete" header, the server yet complete indicated by the "Upload-Complete" header, the server
MUST acknowledge it by responding with the "201 (Created)" status MUST acknowledge it by responding with the "201 (Created)" status
code, the "Upload-Incomplete" header set to true. code, the "Upload-Complete" header set to true.
If the request includes the "Upload-Complete: ?1" header field and a
valid "Content-Length" header field, the client attempts to upload
the remaining resource in one request. In this case, the upload's
final size is the sum of the upload's offset and the "Content-Length"
header field. If the server does not have a record of the upload's
final size from creation or the previous append, the server MUST
record the upload's final size to ensure its consistency. If the
server does have a previous record, that value MUST match the
upload's final size. If they do not match, the server MUST reject
the request with the "400 (Bad Request)" status code.
:method: PATCH :method: PATCH
:scheme: https :scheme: https
:authority: example.com :authority: example.com
:path: /upload/b530ce8ff :path: /upload/b530ce8ff
upload-offset: 100 upload-offset: 100
upload-draft-interop-version: 3 upload-draft-interop-version: 3
content-length: 100 content-length: 100
[content (100 bytes)] [content (100 bytes)]
:status: 201 :status: 201
upload-offset: 200 upload-offset: 200
The client MAY automatically attempt upload resumption when the The client MAY automatically attempt upload resumption when the
connection is terminated unexpectedly, or if a server error status connection is terminated unexpectedly, or if a server error status
code between 500 and 599 (inclusive) is received. The client SHOULD code between 500 and 599 (inclusive) is received. The client SHOULD
NOT automatically retry if a client error status code between 400 and NOT automatically retry if a client error status code between 400 and
499 (inclusive) is received. 499 (inclusive) is received.
7. Upload Cancellation Procedure 7. Upload Cancellation
If the client wants to terminate the transfer without the ability to If the client wants to terminate the transfer without the ability to
resume, it MAY send a "DELETE" request to the upload URL, as obtained resume, it can send a "DELETE" request to the upload resource. Doing
from the Upload Creation Procedure (Section 4). It is an indication so is an indication that the client is no longer interested in
that the client is no longer interested in uploading this body and continuing the upload, and that the server can release any resources
the server can release resources associated with this upload URL. associated with it.
The client MUST NOT initiate this procedure without the knowledge of
The client MUST NOT initiate cancellation without the knowledge of
server support. server support.
The request MUST use the "DELETE" method. The request MUST NOT The request MUST use the "DELETE" method. The request MUST NOT
include the "Upload-Offset" header or the "Upload-Incomplete" header. include the "Upload-Offset" header or the "Upload-Complete" header.
The server MUST reject the request with the "Upload-Offset" header or The server MUST reject the request with the "Upload-Offset" header or
the "Upload-Incomplete" header by sending a "400 (Bad Request)" the "Upload-Complete" header by sending a "400 (Bad Request)"
response. response.
If the server has successfully deactivated this upload URL, it MUST If the server successfully deactivates the upload resource, it MUST
send back a "204 (No Content)" response. send back a "204 (No Content)" response.
The server MAY terminate any ongoing Upload Creation Procedure The server MAY terminate any in-flight requests to the upload
(Section 4) or Upload Appending Procedure (Section 6) for the same resource before sending the response by abruptly terminating their
upload URL before sending the response by abruptly terminating the HTTP connection(s) or stream(s).
HTTP connection or stream.
If the server does not consider the upload associated with this If the server does not consider the upload resource to be active, it
upload URL active, it MUST respond with "404 (Not Found)" status MUST respond with "404 (Not Found)" status code.
code.
If the server does not support cancellation, it MUST respond with If the server does not support cancellation, it MUST respond with
"405 (Method Not Allowed)" status code. "405 (Method Not Allowed)" status code.
:method: DELETE :method: DELETE
:scheme: https :scheme: https
:authority: example.com :authority: example.com
:path: /upload/b530ce8ff :path: /upload/b530ce8ff
upload-draft-interop-version: 3 upload-draft-interop-version: 3
:status: 204 :status: 204
8. Request Identification 8. Header Fields
The Upload Creation Procedure (Section 4) supports arbitrary methods
including "PATCH", therefore it is not possible to identify the
procedure of a request purely by its method. The following algorithm
is RECOMMENDED to identify the procedure from a request for a generic
implementation:
1. The request URL is not an upload URL (i.e. does not point to an
upload resource): Upload Creation Procedure (Section 4)
2. The request URL is an upload URL and the method is "HEAD": Offset
Retrieving Procedure (Section 5).
3. The request URL is an upload URL and the method is "DELETE":
Upload Cancellation Procedure (Section 7).
4. The request URL is an upload URL and the "Upload-Offset" header
is present: Upload Appending Procedure (Section 6).
5. Otherwise: Not a resumable upload.
9. Header Fields
9.1. Upload-Offset 8.1. Upload-Offset
The "Upload-Offset" request and response header field is an Item The "Upload-Offset" request and response header field is an Item
Structured Header indicating the resumption offset of corresponding Structured Header indicating the resumption offset of corresponding
upload, counted in bytes. Its value MUST be an integer. Its ABNF is upload, counted in bytes. Its value MUST be an integer. Its ABNF is
Upload-Offset = sf-integer Upload-Offset = sf-integer
9.2. Upload-Incomplete 8.2. Upload-Complete
The "Upload-Incomplete" request and response header field is an Item The "Upload-Complete" request and response header field is an Item
Structured Header indicating whether the corresponding upload is Structured Header indicating whether the corresponding upload is
considered complete. Its value MUST be a boolean. Its ABNF is considered complete. Its value MUST be a boolean. Its ABNF is
Upload-Incomplete = sf-boolean Upload-Complete = sf-boolean
The "Upload-Incomplete" header field MUST only by used if support by
The "Upload-Complete" header field MUST only by used if support by
the resource is known to the client (Section 4.1). the resource is known to the client (Section 4.1).
10. Redirection 9. Redirection
The "301 (Moved Permanently)" status code and the "302 (Found)" The "301 (Moved Permanently)" status code and the "302 (Found)"
status code MUST NOT be used in Offset Retrieving Procedure status code MUST NOT be used in offset retrieval (Section 5) and
(Section 5) and Upload Cancellation Procedure (Section 7) responses. upload cancellation (Section 7) responses. For other responses, the
A "308 (Permanent Redirect)" response MAY be persisted for all upload resource MAY send a "308 (Permanent Redirect)" response which
subsequent procedures. If client receives a "307 (Temporary clients SHOULD use for subsequent requests to it. If client receives
Redirect)" response in the Offset Retrieving Procedure (Section 5), a "307 (Temporary Redirect)" response to an offset retrieval
it MAY apply the redirection directly in the immediate subsequent (Section 5) request, it MAY apply the redirection directly in an
Upload Appending Procedure (Section 6). immediate subsequent upload append (Section 6).
11. Security Considerations 10. Security Considerations
The upload URL obtained through the Upload Creation Procedure The upload resource URL is the identifier used for modifying the
(Section 4) is the identifier used for modifying the upload. Without upload. Without further protection of this URL, an attacker may
further protection of this upload URL, an attacker may use the upload obtain information about an upload, append data to it, or cancel it.
URL to obtain information about an upload, append data to it, or
cancel it. To prevent this, the server SHOULD ensure that only
authorized clients can perform the Offset Retrieving Procedure
(Section 5), Upload Appending Procedure (Section 6), or Upload
Cancellation Procedure (Section 7) for a given upload URL and
otherwise reject the procedure. In addition, the upload URL SHOULD
be generated in such a way that makes it hard to be guessed by non-
authorized clients.
12. IANA Considerations To prevent this, the server SHOULD ensure that only authorized
clients can access the upload resource. In addition, the upload
resource URL SHOULD be generated in such a way that makes it hard to
be guessed by unauthorized clients.
11. IANA Considerations
This specification registers the following entry in the Permanent This specification registers the following entry in the Permanent
Message Header Field Names registry established by [RFC3864]: Message Header Field Names registry established by [RFC3864]:
Header field name: Upload-Offset, Upload-Incomplete Header field name: Upload-Offset, Upload-Complete
Applicable protocol: http Applicable protocol: http
Status: standard Status: standard
Author/change controller: IETF Author/change controller: IETF
Specification: This document Specification: This document
Related information: n/a Related information: n/a
This specification registers the following entry in the "HTTP Status This specification registers the following entry in the "HTTP Status
Codes" registry: Codes" registry:
Code: 104 (suggested value) Code: 104 (suggested value)
Description: Upload Resumption Supported Description: Upload Resumption Supported
Specification: This document Specification: This document
13. References 12. References
13.1. Normative References 12.1. Normative References
[HTTP] Fielding, R., Nottingham, M., and J. Reschke, "HTTP [HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Semantics", draft-ietf-httpbis-semantics-19 (work in Ed., "HTTP Semantics", STD 97, RFC 9110,
progress), September 2021. DOI 10.17487/RFC9110, June 2022,
<https://www.rfc-editor.org/info/rfc9110>.
[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>.
[RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration
Procedures for Message Header Fields", BCP 90, RFC 3864, Procedures for Message Header Fields", BCP 90, RFC 3864,
DOI 10.17487/RFC3864, September 2004, DOI 10.17487/RFC3864, September 2004,
<https://www.rfc-editor.org/info/rfc3864>. <https://www.rfc-editor.org/info/rfc3864>.
[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>.
[STRUCTURED-FIELDS] [STRUCTURED-FIELDS]
Nottingham, M. and P-H. Kamp, "Structured Field Values for Nottingham, M. and P. Kamp, "Structured Field Values for
HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021, HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021,
<https://www.rfc-editor.org/info/rfc8941>. <https://www.rfc-editor.org/info/rfc8941>.
13.2. URIs 12.2. URIs
[1] https://tus.io/ [1] https://tus.io/
Appendix A. Since draft-ietf-httpbis-resumable-upload-00 Appendix A. Since draft-ietf-httpbis-resumable-upload-01
o Replace Upload-Incomplete header with Upload-Complete.
A.1. Since draft-ietf-httpbis-resumable-upload-00
o Remove Upload-Token and instead use Server-generated upload URL o Remove Upload-Token and instead use Server-generated upload URL
for upload identification. for upload identification.
o Require the Upload-Incomplete header field in Upload Creation o Require the Upload-Incomplete header field in Upload Creation
Procedure. Procedure.
o Increase the draft interop version. o Increase the draft interop version.
A.1. Since draft-tus-httpbis-resumable-uploads-protocol-02 A.2. Since draft-tus-httpbis-resumable-uploads-protocol-02
None None
A.2. Since draft-tus-httpbis-resumable-uploads-protocol-01 A.3. Since draft-tus-httpbis-resumable-uploads-protocol-01
o Clarifying backtracking and preventing skipping ahead during the o Clarifying backtracking and preventing skipping ahead during the
Offset Receiving Procedure. Offset Receiving Procedure.
o Clients auto-retry 404 is no longer allowed. o Clients auto-retry 404 is no longer allowed.
A.3. Since draft-tus-httpbis-resumable-uploads-protocol-00 A.4. Since draft-tus-httpbis-resumable-uploads-protocol-00
o Split the Upload Transfer Procedure into the Upload Creation o Split the Upload Transfer Procedure into the Upload Creation
Procedure and the Upload Appending Procedure. Procedure and the Upload Appending Procedure.
Appendix B. Informational Response Appendix B. Informational Response
The server is allowed to respond to Upload Creation Procedure The server is allowed to respond to upload creation (Section 4)
(Section 4) requests with a "104 (Upload Resumption Supported)" requests with a "104 (Upload Resumption Supported)" intermediate
intermediate response as soon as the server has validated the response as soon as the server has validated the request. This way,
request. This way, the client knows that the server supports the client knows that the server supports resumable uploads before
resumable uploads before the complete response for the Upload the complete response is received. The benefit is the clients can
Creation Procedure is received. The benefit is the clients can defer defer starting the actual data transfer until the server indicates
starting the actual data transfer until the server indicates full full support (i.e. resumable are supported, the provided upload URL
support of the incoming Upload Creation Procedure (i.e. resumable are is active etc).
supported, the provided upload URL is active etc).
On the contrary, support for intermediate responses (the "1XX" range) On the contrary, support for intermediate responses (the "1XX" range)
in existing software is limited or not at all present. Such software in existing software is limited or not at all present. Such software
includes proxies, firewalls, browsers, and HTTP libraries for clients includes proxies, firewalls, browsers, and HTTP libraries for clients
and server. Therefore, the "104 (Upload Resumption Supported)" and server. Therefore, the "104 (Upload Resumption Supported)"
status code is optional and not mandatory for the successful status code is optional and not mandatory for the successful
completion of an upload. Otherwise, it might be impossible in some completion of an upload. Otherwise, it might be impossible in some
cases to implement resumable upload servers using existing software cases to implement resumable upload servers using existing software
packages. Furthermore, as parts of the current internet packages. Furthermore, as parts of the current internet
infrastructure currently have limited support for intermediate infrastructure currently have limited support for intermediate
skipping to change at page 21, line 7 skipping to change at page 20, line 28
is the similar to the above one, with one exception: Instead of a new is the similar to the above one, with one exception: Instead of a new
"104 (Upload Resumption Supported)" status code, the existing "103 "104 (Upload Resumption Supported)" status code, the existing "103
(Early Hint)" status code is used in the intermediate response. The (Early Hint)" status code is used in the intermediate response. The
103 code would then be accompanied by a header indicating support for 103 code would then be accompanied by a header indicating support for
resumable uploads (e.g. "Resumable-Uploads: 1"). It is unclear resumable uploads (e.g. "Resumable-Uploads: 1"). It is unclear
whether the Early Hints code is appropriate for that, as it is whether the Early Hints code is appropriate for that, as it is
currently only used to indicate resources for prefetching them. currently only used to indicate resources for prefetching them.
Appendix D. Upload Metadata Appendix D. Upload Metadata
The Upload Creation Procedure (Section 4) allows the "Content-Type" When an upload is created (Section 4), the "Content-Type" and
and "Content-Disposition" header to be included. They are intended "Content-Disposition" header are allowed to be included. They are
to be a standardized way of communicating the file name and file intended to be a standardized way of communicating the file name and
type, if available. However, this is not without controversy. Some file type, if available. However, this is not without controversy.
argue that since these headers are already defined in other Some argue that since these headers are already defined in other
specifications, it is not necessary to include them here again. specifications, it is not necessary to include them here again.
Furthermore, the "Content-Disposition" header field's format is not Furthermore, the "Content-Disposition" header field's format is not
clearly enough defined. For example, it is left open which clearly enough defined. For example, it is left open which
disposition value should be used in the header. There needs to be disposition value should be used in the header. There needs to be
more discussion whether this approach is suited or not. more discussion whether this approach is suited or not.
However, from experience with the tus project, users are often asking However, from experience with the tus project, users are often asking
for a way to communicate the file name and file type. Therefore, we 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. believe it is help to explicitly include an approach for doing so.
Appendix E. FAQ Appendix E. FAQ
o *Are multipart requests supported?* Yes, requests whose body is o *Are multipart requests supported?* Yes, requests whose content is
encoded using the "multipart/form-data" are implicitly supported. encoded using the "multipart/form-data" are implicitly supported.
The entire encoded body can be considered as a single file, which The entire encoded content can be considered as a single file,
is then uploaded using the resumable protocol. The server, of which is then uploaded using the resumable protocol. The server,
course, must store the delimiter ("boundary") separating each part of course, must store the delimiter ("boundary") separating each
and must be able to parse the multipart format once the upload is part and must be able to parse the multipart format once the
completed. 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.
 End of changes. 103 change blocks. 
328 lines changed or deleted 297 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/