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/ |