draft-ietf-httpbis-resumable-upload-03.txt   draft-ietf-httpbis-resumable-upload-latest.txt 
HTTP Working Group M. Kleidl, Ed. HTTP Working Group M. Kleidl, Ed.
Internet-Draft Transloadit Internet-Draft Transloadit
Intended status: Standards Track G. Zhang, Ed. Intended status: Standards Track G. Zhang, Ed.
Expires: September 5, 2024 Apple Inc. Expires: September 26, 2024 Apple Inc.
L. Pardue, Ed. L. Pardue, Ed.
Cloudflare Cloudflare
March 4, 2024 March 25, 2024
Resumable Uploads for HTTP Resumable Uploads for HTTP
draft-ietf-httpbis-resumable-upload-03 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 5, 2024. This Internet-Draft will expire on September 26, 2024.
Copyright Notice Copyright Notice
Copyright (c) 2024 IETF Trust and the persons identified as the Copyright (c) 2024 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
skipping to change at page 3, line 9 skipping to change at page 3, line 9
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17
12. References . . . . . . . . . . . . . . . . . . . . . . . . . 17 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 17
12.1. Normative References . . . . . . . . . . . . . . . . . . 18 12.1. Normative References . . . . . . . . . . . . . . . . . . 18
12.2. Informative References . . . . . . . . . . . . . . . . . 18 12.2. Informative References . . . . . . . . . . . . . . . . . 18
Appendix A. Informational Response . . . . . . . . . . . . . . . 18 Appendix A. Informational Response . . . . . . . . . . . . . . . 18
Appendix B. Feature Detection . . . . . . . . . . . . . . . . . 19 Appendix B. Feature Detection . . . . . . . . . . . . . . . . . 19
Appendix C. Upload Metadata . . . . . . . . . . . . . . . . . . 21 Appendix C. Upload Metadata . . . . . . . . . . . . . . . . . . 21
Appendix D. FAQ . . . . . . . . . . . . . . . . . . . . . . . . 21 Appendix D. FAQ . . . . . . . . . . . . . . . . . . . . . . . . 21
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 21 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 21
Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
F.1. Since draft-ietf-httpbis-resumable-upload-02 . . . . . . 22 F.1. Since draft-ietf-httpbis-resumable-upload-03 . . . . . . 22
F.2. Since draft-ietf-httpbis-resumable-upload-01 . . . . . . 22 F.2. Since draft-ietf-httpbis-resumable-upload-02 . . . . . . 22
F.3. Since draft-ietf-httpbis-resumable-upload-00 . . . . . . 22 F.3. Since draft-ietf-httpbis-resumable-upload-01 . . . . . . 22
F.4. Since draft-tus-httpbis-resumable-uploads-protocol-02 . . 23 F.4. Since draft-ietf-httpbis-resumable-upload-00 . . . . . . 22
F.5. Since draft-tus-httpbis-resumable-uploads-protocol-01 . . 23 F.5. Since draft-tus-httpbis-resumable-uploads-protocol-02 . . 23
F.6. Since draft-tus-httpbis-resumable-uploads-protocol-00 . . 23 F.6. Since draft-tus-httpbis-resumable-uploads-protocol-01 . . 23
F.7. Since draft-tus-httpbis-resumable-uploads-protocol-00 . . 23
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 23 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 23
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 5, line 19 skipping to change at page 5, line 19
| POST | | POST |
|------------------------------------------->| |------------------------------------------->|
| | | |
| | Reserve resources | | Reserve resources
| | for upload | | for upload
| |-----------------. | |-----------------.
| | | | | |
| |<----------------' | |<----------------'
| | | |
| 104 Upload Resumption Supported | | 104 Upload Resumption Supported |
| with upload resouce URL | | with upload resource URL |
|<-------------------------------------------| |<-------------------------------------------|
| | | |
| Flow Interrupted | | Flow Interrupted |
|------------------------------------------->| |------------------------------------------->|
| | | |
Figure 1: Upload Creation Figure 1: Upload Creation
2) If the connection to the server is interrupted, the client might 2) If the connection to the server is interrupted, the client might
want to resume the upload. However, before this is possible the want to resume the upload. However, before this is possible the
skipping to change at page 8, line 38 skipping to change at page 8, line 38
success (e.g. "201 (Created)"), or when the response is a failure success (e.g. "201 (Created)"), or when the response is a failure
(e.g. "409 (Conflict)"). The "Upload-Offset" field value MUST be (e.g. "409 (Conflict)"). The "Upload-Offset" field value MUST be
equal to the end offset of the entire upload, or the begin offset of equal to the end offset of the entire upload, or the begin offset of
the next chunk if the upload is still incomplete. The client SHOULD the next chunk if the upload is still incomplete. The client SHOULD
consider the upload failed if the response has a status code that consider the upload failed if the response has a status code that
indicates a success but the offset indicated in the "Upload-Offset" indicates a success but the offset indicated in the "Upload-Offset"
field value does not equal the total of begin offset plus the number field value does not equal the total of begin offset plus the number
of bytes uploaded in the request. of bytes uploaded in the request.
If the request completes successfully and the entire upload is If the request completes successfully and the entire upload is
complete, the server MUST acknowledge it by responding with a complete, the server MUST acknowledge it by responding with a 2xx
successful status code between 200 and 299 (inclusive). Servers are (Successful) status code. Servers are RECOMMENDED to use "201
RECOMMENDED to use "201 (Created)" unless otherwise specified. The (Created)" unless otherwise specified. The response MUST NOT include
response MUST NOT include the "Upload-Complete" header field with the the "Upload-Complete" header field with the value of false.
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, as indicated by an "Upload-Complete" field value of yet complete, as indicated by an "Upload-Complete" field value of
false in the request, the server MUST acknowledge it by responding false in the request, the server MUST acknowledge it by responding
with the "201 (Created)" status code and an "Upload-Complete" header with the "201 (Created)" status code and an "Upload-Complete" header
value set to false. value set to false.
If the request includes an "Upload-Complete" field value set to true If the request includes an "Upload-Complete" field value set to true
and a valid "Content-Length" header field, the client attempts to and a valid "Content-Length" header field, the client attempts to
upload a fixed-length resource in one request. In this case, the upload a fixed-length resource in one request. In this case, the
upload's final size is the "Content-Length" field value and the upload's final size is the "Content-Length" field value and the
server MUST record it to ensure its consistency. server MUST record it to ensure its consistency.
The request content MAY be empty. If the "Upload-Complete" header The request content MAY be empty. If the "Upload-Complete" header
field is then set to true, the client intends to upload an empty field is then set to true, the client intends to upload an empty
entity. An "Upload-Complete" header field is set to false is also resource representation. An "Upload-Complete" header field is set to
valid. This can be used to create an upload resource URL before false is also valid. This can be used to create an upload resource
transferring data, which can save client or server resources. Since URL before transferring data, which can save client or server
informational responses are optional, this technique provides another resources. Since informational responses are optional, this
mechanism to learn the URL, at the cost of an additional round-trip technique provides another mechanism to learn the URL, at the cost of
before data upload can commence. an additional round-trip before data upload can commence.
The following example shows an upload creation. The client transfers The following example shows an upload creation. The client transfers
the entire 100 bytes in the first request. The server generates two the entire 100 bytes in the first request. The server generates two
informational responses to transmit the upload resource's URL and informational responses to transmit the upload resource's URL and
progress information, and one final response to acknowledge the progress information, and one final response to acknowledge the
completed upload: completed upload:
POST /upload HTTP/1.1 POST /upload HTTP/1.1
Host: example.com Host: example.com
Upload-Draft-Interop-Version: 5 Upload-Draft-Interop-Version: 5
skipping to change at page 10, line 28 skipping to change at page 10, line 28
If the client received an informational response with the upload URL If the client received an informational response with the upload URL
in the Location field value, it MAY automatically attempt upload in the Location field value, it MAY automatically attempt upload
resumption when the connection is terminated unexpectedly, or if a resumption when the connection is terminated unexpectedly, or if a
5xx status is received. The client SHOULD NOT automatically retry if 5xx status is received. The client SHOULD NOT automatically retry if
it receives a 4xx status code. it receives a 4xx status code.
File metadata can affect how servers might act on the uploaded file. 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 request that starts an upload. Servers MAY interpret this in the request that starts an upload. Servers MAY interpret this
metadata or MAY ignore it. The "Content-Type" header field metadata or MAY ignore it. The "Content-Type" header field
(Section 8.3 of [HTTP]) can be used to indicate the MIME type of the (Section 8.3 of [HTTP]) can be used to indicate the media type of the
file. The "Content-Disposition" header field ([RFC6266]) can be used file. The "Content-Disposition" header field ([RFC6266]) can be used
to transmit a filename; if included, the parameters SHOULD be either to transmit a filename; if included, the parameters SHOULD be either
"filename", "filename*" or "boundary". "filename", "filename*" or "boundary".
4.1. Feature Detection 4.1. Feature Detection
If the client has no knowledge of whether the resource supports If the client has no knowledge of whether the resource supports
resumable uploads, a resumable request can be used with some resumable uploads, a resumable request can be used with some
additional constraints. In particular, the "Upload-Complete" field additional constraints. In particular, the "Upload-Complete" field
value (Section 8.2) MUST NOT be false if the server support is value (Section 8.2) MUST NOT be false if the server support is
skipping to change at page 12, line 20 skipping to change at page 12, line 20
successfully received a corresponding creation request (Section 4) or successfully received a corresponding creation request (Section 4) or
append request (Section 6) with the "Upload-Complete" header value append request (Section 6) with the "Upload-Complete" header value
set to true. set to true.
The client MUST NOT perform offset retrieval while creation The client MUST NOT perform offset retrieval while creation
(Section 4) or append (Section 6) is in progress. (Section 4) or append (Section 6) is in progress.
The offset MUST be accepted by a subsequent append (Section 6). Due The offset MUST be accepted by a subsequent append (Section 6). Due
to network delay and reordering, the server might still be receiving to network delay and reordering, the server might still be receiving
data from an ongoing transfer for the same upload resource, which in data from an ongoing transfer for the same upload resource, which in
the client perspective has failed. The server MAY terminate any the client's perspective has failed. The server MAY terminate any
transfers for the same upload resource before sending the response by transfers for the same upload resource before sending the response by
abruptly terminating the HTTP connection or stream. Alternatively, abruptly terminating the HTTP connection or stream. Alternatively,
the server MAY keep the ongoing transfer alive but ignore further the server MAY keep the ongoing transfer alive but ignore further
bytes received past the offset. bytes received past the offset.
The client MUST NOT start more than one append (Section 6) based on The client MUST NOT start more than one append (Section 6) based on
the resumption offset from a single offset retrieving (Section 5) the resumption offset from a single offset retrieving (Section 5)
request. request.
In order to prevent HTTP caching, the response SHOULD include a In order to prevent HTTP caching, the response SHOULD include a
skipping to change at page 13, line 9 skipping to change at page 13, line 9
indicates the new offset and that the upload is not complete yet: indicates the new offset and that the upload is not complete yet:
HEAD /upload/b530ce8ff HTTP/1.1 HEAD /upload/b530ce8ff HTTP/1.1
Host: example.com Host: example.com
Upload-Draft-Interop-Version: 5 Upload-Draft-Interop-Version: 5
HTTP/1.1 204 No Content HTTP/1.1 204 No Content
Upload-Offset: 100 Upload-Offset: 100
Upload-Complete: ?0 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 4xx (Client Error)
code between 400 and 499 (inclusive) is received. status code is received.
6. Upload Append 6. Upload Append
Upload appending is used for resuming an existing upload. Upload appending is used for resuming an existing upload.
The request MUST use the "PATCH" method and be sent to the upload The request MUST use the "PATCH" method and be sent to the upload
resource. The "Upload-Offset" field value (Section 8.1) MUST be set resource. The "Upload-Offset" field value (Section 8.1) MUST be set
to the resumption offset. to the resumption offset.
If the end of the request content is not the end of the upload, the If the end of the request content is not the end of the upload, the
skipping to change at page 14, line 20 skipping to change at page 14, line 20
if it considers the upload active, either when the response is a if it considers the upload active, either when the response is a
success (e.g. "201 (Created)"), or when the response is a failure success (e.g. "201 (Created)"), or when the response is a failure
(e.g. "409 (Conflict)"). The value MUST be equal to the end offset (e.g. "409 (Conflict)"). The value MUST be equal to the end offset
of the entire upload, or the begin offset of the next chunk if the of the entire upload, or the begin offset of the next chunk if the
upload is still incomplete. The client SHOULD consider the upload upload is still incomplete. The client SHOULD consider the upload
failed if the status code indicates a success but the offset failed if the status code indicates a success but the offset
indicated by the "Upload-Offset" field value does not equal the total indicated by the "Upload-Offset" field value does not equal the total
of begin offset plus the number of bytes uploaded in the request. of begin offset plus the number of bytes uploaded in the request.
If the 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 2xx
successful status code between 200 and 299 (inclusive). Servers are (Successful) status code. Servers are RECOMMENDED to use a "201
RECOMMENDED to use a "201 (Created)" response if not otherwise (Created)" response if not otherwise specified. The response MUST
specified. The response MUST NOT include the "Upload-Complete" NOT include the "Upload-Complete" header field with the value set to
header field with the value set to false. 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-Complete" field value set to yet complete indicated by the "Upload-Complete" field value set to
false, the server MUST acknowledge it by responding with a "201 false, the server MUST acknowledge it by responding with a "201
(Created)" status code and the "Upload-Complete" field value set to (Created)" status code and the "Upload-Complete" field value set to
true. true.
If the request includes the "Upload-Complete" field value set to true If the request includes the "Upload-Complete" field value set to true
and a valid "Content-Length" header field, the client attempts to and a valid "Content-Length" header field, the client attempts to
upload the remaining resource in one request. In this case, the upload the remaining resource in one request. In this case, the
skipping to change at page 15, line 17 skipping to change at page 15, line 17
Upload-Offset: 100 Upload-Offset: 100
Upload-Draft-Interop-Version: 5 Upload-Draft-Interop-Version: 5
Content-Length: 100 Content-Length: 100
[content (100 bytes)] [content (100 bytes)]
HTTP/1.1 201 Created HTTP/1.1 201 Created
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 5xx (Server Error)
code between 500 and 599 (inclusive) is received. The client SHOULD status code is received. The client SHOULD NOT automatically retry
NOT automatically retry if a client error status code between 400 and if a 4xx (Client Error) status code is received.
499 (inclusive) is received.
7. Upload Cancellation 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 can send a "DELETE" request to the upload resource. Doing resume, it can send a "DELETE" request to the upload resource. Doing
so is an indication that the client is no longer interested in so is an indication that the client is no longer interested in
continuing the upload, and that the server can release any resources continuing the upload, and that the server can release any resources
associated with it. associated with it.
The client MUST NOT initiate cancellation without the knowledge of The client MUST NOT initiate cancellation without the knowledge of
skipping to change at page 22, line 14 skipping to change at page 22, line 14
protocol. Members of the tus community helped significantly in the protocol. Members of the tus community helped significantly in the
process of bringing this work to the IETF. process of bringing this work to the IETF.
The authors would like to thank Mark Nottingham for substantive The authors would like to thank Mark Nottingham for substantive
contributions to the text. contributions to the text.
Changes Changes
This section is to be removed before publishing as an RFC. This section is to be removed before publishing as an RFC.
F.1. Since draft-ietf-httpbis-resumable-upload-02 F.1. Since draft-ietf-httpbis-resumable-upload-03
None yet.
F.2. Since draft-ietf-httpbis-resumable-upload-02
o Add upload progress notifications via informational responses. o Add upload progress notifications via informational responses.
o Add security consideration regarding request filtering. o Add security consideration regarding request filtering.
o Explain the use of empty requests for creation uploads and o Explain the use of empty requests for creation uploads and
appending. appending.
o Extend security consideration to include resource exhaustion o Extend security consideration to include resource exhaustion
attacks. attacks.
o Allow 200 status codes for offset retrieval. o Allow 200 status codes for offset retrieval.
o Increase the draft interop version. o Increase the draft interop version.
F.2. Since draft-ietf-httpbis-resumable-upload-01 F.3. Since draft-ietf-httpbis-resumable-upload-01
o Replace Upload-Incomplete header with Upload-Complete. o Replace Upload-Incomplete header with Upload-Complete.
o Replace terminology about procedures with HTTP resources. o Replace terminology about procedures with HTTP resources.
o Increase the draft interop version. o Increase the draft interop version.
F.3. Since draft-ietf-httpbis-resumable-upload-00 F.4. Since draft-ietf-httpbis-resumable-upload-00
o Remove Upload-Token and instead use Server-generated upload URL o Remove Upload-Token and instead use Server-generated upload URL
for upload identification. for upload identification.
o Require the Upload-Incomplete header field in Upload Creation o Require the Upload-Incomplete header field in Upload Creation
Procedure. Procedure.
o Increase the draft interop version. o Increase the draft interop version.
F.4. Since draft-tus-httpbis-resumable-uploads-protocol-02 F.5. Since draft-tus-httpbis-resumable-uploads-protocol-02
None None
F.5. Since draft-tus-httpbis-resumable-uploads-protocol-01 F.6. Since draft-tus-httpbis-resumable-uploads-protocol-01
o Clarifying backtracking and preventing skipping ahead during the o Clarifying backtracking and preventing skipping ahead during the
Offset Receiving Procedure. Offset Receiving Procedure.
o Clients auto-retry 404 is no longer allowed. o Clients auto-retry 404 is no longer allowed.
F.6. Since draft-tus-httpbis-resumable-uploads-protocol-00 F.7. Since draft-tus-httpbis-resumable-uploads-protocol-00
o Split the Upload Transfer Procedure into the Upload Creation o Split the Upload Transfer Procedure into the Upload Creation
Procedure and the Upload Appending Procedure. Procedure and the Upload Appending Procedure.
Authors' Addresses Authors' Addresses
Marius Kleidl (editor) Marius Kleidl (editor)
Transloadit Transloadit
Email: marius@transloadit.com Email: marius@transloadit.com
 End of changes. 19 change blocks. 
41 lines changed or deleted 44 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/