draft-ietf-httpbis-resumable-upload-00.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: March 9, 2023 Apple Inc. Expires: August 10, 2023 Apple Inc.
L. Pardue, Ed. L. Pardue, Ed.
Cloudflare Cloudflare
September 5, 2022 February 06, 2023
tus - Resumable Uploads Protocol tus - Resumable Uploads Protocol
draft-ietf-httpbis-resumable-upload-00 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 March 9, 2023. This Internet-Draft will expire on August 10, 2023.
Copyright Notice Copyright Notice
Copyright (c) 2022 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. Uploading Overview . . . . . . . . . . . . . . . . . . . . . 4
3.1. Example 1: Complete upload of file with known size . . . 5 3.1. Example 1: Complete upload of file with known size . . . 5
3.2. Example 2: Upload as a series of parts . . . . . . . . . 7 3.2. Example 2: Upload as a series of parts . . . . . . . . . 7
4. Upload Creation Procedure . . . . . . . . . . . . . . . . . . 7 4. Upload Creation Procedure . . . . . . . . . . . . . . . . . . 8
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 Retrieving Procedure . . . . . . . . . . . . . . . . . 11
6. Upload Appending Procedure . . . . . . . . . . . . . . . . . 12 6. Upload Appending Procedure . . . . . . . . . . . . . . . . . 12
7. Upload Cancellation Procedure . . . . . . . . . . . . . . . . 14 7. Upload Cancellation Procedure . . . . . . . . . . . . . . . . 14
8. Request Identification . . . . . . . . . . . . . . . . . . . 15 8. Request Identification . . . . . . . . . . . . . . . . . . . 15
9. Header Fields . . . . . . . . . . . . . . . . . . . . . . . . 15 9. Header Fields . . . . . . . . . . . . . . . . . . . . . . . . 15
9.1. Upload-Token . . . . . . . . . . . . . . . . . . . . . . 15 9.1. Upload-Token . . . . . . . . . . . . . . . . . . . . . . 15
9.2. Upload-Offset . . . . . . . . . . . . . . . . . . . . . . 16 9.2. Upload-Offset . . . . . . . . . . . . . . . . . . . . . . 16
9.3. Upload-Incomplete . . . . . . . . . . . . . . . . . . . . 16 9.3. Upload-Incomplete . . . . . . . . . . . . . . . . . . . . 16
10. Redirection . . . . . . . . . . . . . . . . . . . . . . . . . 16 10. Redirection . . . . . . . . . . . . . . . . . . . . . . . . . 16
11. Security Considerations . . . . . . . . . . . . . . . . . . . 16 11. Security Considerations . . . . . . . . . . . . . . . . . . . 16
12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17
13. Normative References . . . . . . . . . . . . . . . . . . . . 17 13. Normative References . . . . . . . . . . . . . . . . . . . . 17
Appendix A. Changes . . . . . . . . . . . . . . . . . . . . . . 18 Appendix A. Changes . . . . . . . . . . . . . . . . . . . . . . 18
A.1. Since draft-tus-httpbis-resumable-uploads-protocol-01 . . 18 A.1. Since draft-tus-httpbis-resumable-uploads-protocol-01 . . 18
A.2. Since draft-tus-httpbis-resumable-uploads-protocol-00 . . 18 A.2. Since draft-tus-httpbis-resumable-uploads-protocol-00 . . 18
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 18 Appendix B. Informational Response . . . . . . . . . . . . . . . 18
Appendix . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Appendix C. Feature Detection . . . . . . . . . . . . . . . . . 19
C.1. Informational Response . . . . . . . . . . . . . . . . . 18 Appendix D. Upload Metadata . . . . . . . . . . . . . . . . . . 21
C.2. Feature Detection . . . . . . . . . . . . . . . . . . . . 19 Appendix E. FAQ . . . . . . . . . . . . . . . . . . . . . . . . 21
C.3. Upload Metadata . . . . . . . . . . . . . . . . . . . . . 21 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 21
C.4. FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . 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
that transfer only the remainder of the representation. HTTP range that transfer only the remainder of the representation. HTTP range
skipping to change at page 7, line 19 skipping to change at page 7, line 19
overcome server limits on HTTP message content size. Another use 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 over a
sequence of procedures. sequence of procedures.
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 use the Upload Creation Procedure with the "Upload-Incomplete"
header to start an upload. header to start an upload. The client can include the first part of
the file in the Upload Creation Procedure.
Client Server Client Server
| | | |
| POST with Upload-Token and Upload-Incomplete | | POST with Upload-Token and Upload-Incomplete |
|----------------------------------------------->| |----------------------------------------------->|
| | | |
| 201 Created with Upload-Incomplete | | 201 Created with Upload-Incomplete |
| on completion | | on completion |
|<-----------------------------------------------| |<-----------------------------------------------|
| | | |
skipping to change at page 10, line 7 skipping to change at page 10, line 7
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 Upload Creation Procedure request that starts an upload.
Servers MAY interpret this metadata or MAY ignore it. The "Content- Servers MAY interpret this metadata or MAY ignore it. The "Content-
Type" header can be used to indicate the MIME type of the file. The Type" header can be used to indicate the MIME type of the file. The
"Content-Disposition" header can be used to transmit a filename. If "Content-Disposition" header can be used to transmit a filename. If
included, the parameters SHOULD be either "filename", "filename*" or included, the parameters 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 server supports If the client has no knowledge of whether the resource supports
resumable upload, the Upload Creation Procedure MAY be used with some resumable uploads, the Upload Creation Procedure MAY be used with
additional constraints. In particular, the "Upload-Incomplete" some additional constraints. In particular, the "Upload-Incomplete"
header field (Section 9.3) MUST NOT be sent in the request if the header field (Section 9.3) MUST NOT be sent in the request if the
server support is unclear. This allows the upload to function as if support of resumable uploads by the resource is unclear. This allows
it is a regular upload. the upload to function as if it is a regular upload.
If the server detects the Upload Creation Procedure and it supports If the server detects the Upload Creation Procedure and it supports
resumable upload, an informational response with "104 (Upload resumable upload, an informational response with "104 (Upload
Resumption Supported)" status MAY be sent to the client while the Resumption Supported)" status MAY be sent to the client while the
request body is being uploaded. request body is being uploaded.
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 supporting
resumable upload. resumable upload.
skipping to change at page 13, line 27 skipping to change at page 13, line 27
measures to avoid parallel upload transfers: The server MAY terminate measures to avoid parallel upload transfers: The server MAY terminate
any ongoing Upload Creation Procedure (Section 4) or Upload Appending any ongoing Upload Creation Procedure (Section 4) or Upload Appending
Procedure (Section 6) for the same token. Since the client is not Procedure (Section 6) for the same token. Since the client is not
allowed to perform multiple transfers in parallel, the server can allowed to perform multiple transfers in parallel, the server can
assume that the previous attempt has already failed. Therefore, the assume that the previous attempt has already failed. Therefore, the
server MAY abruptly terminate the previous HTTP 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 Retrieving Procedure
(Section 5), or the end offset of the immediate previous incomplete (Section 5), or the end offset of the immediate previous incomplete
transfer, the server MUST respond with "409 (Conflict)" status code. successful transfer, the server MUST respond with "409 (Conflict)"
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.
skipping to change at page 16, line 21 skipping to change at page 16, line 21
Upload-Offset = sf-integer Upload-Offset = sf-integer
9.3. Upload-Incomplete 9.3. Upload-Incomplete
The "Upload-Incomplete" request and response header field is an Item The "Upload-Incomplete" 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-Incomplete = sf-boolean
The "Upload-Incomplete" header field MUST only by used if support by
the resource is known to the client (Section 4.1).
10. Redirection 10. 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 Retrieving Procedure
(Section 5) and Upload Cancellation Procedure (Section 7) responses. (Section 5) and Upload Cancellation Procedure (Section 7) responses.
A "308 (Permanent Redirect)" response MAY be persisted for all A "308 (Permanent Redirect)" response MAY be persisted for all
subsequent procedures. If client receives a "307 (Temporary subsequent procedures. If client receives a "307 (Temporary
Redirect)" response in the Offset Retrieving Procedure (Section 5), Redirect)" response in the Offset Retrieving Procedure (Section 5),
it MAY apply the redirection directly in the immediate subsequent it MAY apply the redirection directly in the immediate subsequent
Upload Appending Procedure (Section 6). Upload Appending Procedure (Section 6).
skipping to change at page 17, line 25 skipping to change at page 17, line 33
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. Normative References 13. Normative References
[HTTP] Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP [HTTP] Fielding, R., Nottingham, M., and J. Reschke, "HTTP
Semantics", draft-ietf-httpbis-semantics-19 (work in Semantics", draft-ietf-httpbis-semantics-19 (work in
progress), September 2021. progress), September 2021.
[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,
skipping to change at page 18, line 19 skipping to change at page 18, line 24
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.2. Since draft-tus-httpbis-resumable-uploads-protocol-00 A.2. 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.
Acknowledgments Appendix B. Informational Response
This document is based on an Internet-Draft specification written by
Jiten Mehta, Stefan Matsson, and the authors of this document.
TODO: more acknowledgements.
Appendix
C.1. Informational Response
The server is allowed to respond to Upload Creation Procedure The server is allowed to respond to Upload Creation Procedure
(Section 4) requests with a "104 (Upload Resumption Supported)" (Section 4) requests with a "104 (Upload Resumption Supported)"
intermediate response as soon as the server has validated the intermediate response as soon as the server has validated the
request. This way, the client knows that the server supports request. This way, the client knows that the server supports
resumable uploads before the complete response for the Upload resumable uploads before the complete response for the Upload
Creation Procedure is received. The benefit is the clients can defer Creation Procedure is received. The benefit is the clients can defer
starting the actual data transfer until the server indicates full starting the actual data transfer until the server indicates full
support of the incoming Upload Creation Procedure (i.e. resumable are support of the incoming Upload Creation Procedure (i.e. resumable are
supported, the provided upload token is active etc). supported, the provided upload token is active etc).
skipping to change at page 19, line 9 skipping to change at page 19, line 5
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
responses, a successful delivery of a "104 (Upload Resumption responses, a successful delivery of a "104 (Upload Resumption
Supported)" from the server to the client should be assumed. Supported)" from the server to the client should be assumed.
We hope that support for intermediate responses increases in the near We hope that support for intermediate responses increases in the near
future, to allow a wider usage of "104 (Upload Resumption future, to allow a wider usage of "104 (Upload Resumption
Supported)". Supported)".
C.2. Feature Detection Appendix C. Feature Detection
This specification includes a section about feature detection (it was This specification includes a section about feature detection (it was
called service discovery in earlier discussions, but this name is called service discovery in earlier discussions, but this name is
probably ill-suited). The idea is to allow resumable uploads to be probably ill-suited). The idea is to allow resumable uploads to be
transparently implemented by HTTP clients. This means that transparently implemented by HTTP clients. This means that
application developers just keep using the same API of their HTTP application developers just keep using the same API of their HTTP
library as they have done in the past with traditional, non-resumable library as they have done in the past with traditional, non-resumable
uploads. Once the HTTP library gets updated (e.g. because mobile OS uploads. Once the HTTP library gets updated (e.g. because mobile OS
or browsers start implementing resumable uploads), the HTTP library or browsers start implementing resumable uploads), the HTTP library
can transparently decide to use resumable uploads without explicit can transparently decide to use resumable uploads without explicit
skipping to change at page 21, line 7 skipping to change at page 21, line 5
*Send a 103 Early Hint response to indicate support.* This approach *Send a 103 Early Hint response to indicate support.* This approach
is the similar to the above one, with one exception: Instead of a new 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.
C.3. Upload Metadata Appendix D. Upload Metadata
The Upload Creation Procedure (Section 4) allows the "Content-Type" The Upload Creation Procedure (Section 4) allows the "Content-Type"
and "Content-Disposition" header to be included. They are intended and "Content-Disposition" header to be included. They are intended
to be a standardized way of communicating the file name and file to be a standardized way of communicating the file name and file
type, if available. However, this is not without controversy. Some type, if available. However, this is not without controversy. Some
argue that since these headers are already defined in other 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.
C.4. FAQ Appendix E. FAQ
o *Are multipart requests supported?* Yes, requests whose body is o *Are multipart requests supported?* Yes, requests whose body 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 body can be considered as a single file, which
is then uploaded using the resumable protocol. The server, of is then uploaded using the resumable protocol. The server, of
course, must store the delimiter ("boundary") separating each part course, must store the delimiter ("boundary") separating each part
and must be able to parse the multipart format once the upload is and must be able to parse the multipart format once the upload is
completed. completed.
Acknowledgments
This document is based on an Internet-Draft specification written by
Jiten Mehta, Stefan Matsson, and the authors of this document.
TODO: more acknowledgements.
Authors' Addresses Authors' Addresses
Marius Kleidl (editor) Marius Kleidl (editor)
Transloadit Ltd Transloadit Ltd
Email: marius@transloadit.com Email: marius@transloadit.com
Guoye Zhang (editor) Guoye Zhang (editor)
Apple Inc. Apple Inc.
 End of changes. 19 change blocks. 
34 lines changed or deleted 36 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/