draft-ietf-httpbis-resumable-upload-05.txt   draft-ietf-httpbis-resumable-upload-latest.txt 
HTTP Working Group M. Kleidl, Ed. HTTP Working Group M. Kleidl, Ed.
Internet-Draft Transloadit Internet-Draft Transloadit
Intended status: Standards Track G. Zhang, Ed. Intended status: Standards Track G. Zhang, Ed.
Expires: April 24, 2025 Apple Inc. Expires: August 7, 2025 Apple Inc.
L. Pardue, Ed. L. Pardue, Ed.
Cloudflare Cloudflare
October 21, 2024 February 03, 2025
Resumable Uploads for HTTP Resumable Uploads for HTTP
draft-ietf-httpbis-resumable-upload-05 draft-ietf-httpbis-resumable-upload-latest
Abstract Abstract
HTTP clients often encounter interrupted data transfers as a result HTTP clients often encounter interrupted data transfers as a result
of canceled requests or dropped connections. Prior to interruption, of canceled requests or dropped connections. Prior to interruption,
part of a representation may have been exchanged. To complete the part of a representation may have been exchanged. To complete the
data transfer of the entire representation, it is often desirable to 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 April 24, 2025. This Internet-Draft will expire on August 7, 2025.
Copyright Notice Copyright Notice
Copyright (c) 2024 IETF Trust and the persons identified as the Copyright (c) 2025 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
skipping to change at page 3, line 26 skipping to change at page 3, line 26
19. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26 19. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26
20. References . . . . . . . . . . . . . . . . . . . . . . . . . 28 20. References . . . . . . . . . . . . . . . . . . . . . . . . . 28
20.1. Normative References . . . . . . . . . . . . . . . . . . 28 20.1. Normative References . . . . . . . . . . . . . . . . . . 28
20.2. Informative References . . . . . . . . . . . . . . . . . 29 20.2. Informative References . . . . . . . . . . . . . . . . . 29
Appendix A. Informational Response . . . . . . . . . . . . . . . 29 Appendix A. Informational Response . . . . . . . . . . . . . . . 29
Appendix B. Feature Detection . . . . . . . . . . . . . . . . . 30 Appendix B. Feature Detection . . . . . . . . . . . . . . . . . 30
Appendix C. Upload Metadata . . . . . . . . . . . . . . . . . . 32 Appendix C. Upload Metadata . . . . . . . . . . . . . . . . . . 32
Appendix D. FAQ . . . . . . . . . . . . . . . . . . . . . . . . 32 Appendix D. FAQ . . . . . . . . . . . . . . . . . . . . . . . . 32
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 32 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 32
Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
F.1. Since draft-ietf-httpbis-resumable-upload-04 . . . . . . 33 F.1. Since draft-ietf-httpbis-resumable-upload-05 . . . . . . 33
F.2. Since draft-ietf-httpbis-resumable-upload-03 . . . . . . 33 F.2. Since draft-ietf-httpbis-resumable-upload-04 . . . . . . 33
F.3. Since draft-ietf-httpbis-resumable-upload-02 . . . . . . 33 F.3. Since draft-ietf-httpbis-resumable-upload-03 . . . . . . 33
F.4. Since draft-ietf-httpbis-resumable-upload-01 . . . . . . 34 F.4. Since draft-ietf-httpbis-resumable-upload-02 . . . . . . 33
F.5. Since draft-ietf-httpbis-resumable-upload-00 . . . . . . 34 F.5. Since draft-ietf-httpbis-resumable-upload-01 . . . . . . 34
F.6. Since draft-tus-httpbis-resumable-uploads-protocol-02 . . 34 F.6. Since draft-ietf-httpbis-resumable-upload-00 . . . . . . 34
F.7. Since draft-tus-httpbis-resumable-uploads-protocol-01 . . 34 F.7. Since draft-tus-httpbis-resumable-uploads-protocol-02 . . 34
F.8. Since draft-tus-httpbis-resumable-uploads-protocol-00 . . 34 F.8. Since draft-tus-httpbis-resumable-uploads-protocol-01 . . 34
F.9. Since draft-tus-httpbis-resumable-uploads-protocol-00 . . 34
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 34 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 34
1. Introduction 1. Introduction
HTTP clients often encounter interrupted data transfers as a result HTTP clients often encounter interrupted data transfers as a result
of canceled requests or dropped connections. Prior to interruption, of canceled requests or dropped connections. Prior to interruption,
part of a representation (see Section 3.2 of [HTTP]) might have been part of a representation (see Section 3.2 of [HTTP]) might have been
exchanged. To complete the data transfer of the entire exchanged. To complete the 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 16, line 16 skipping to change at page 16, line 16
complete, the server MUST acknowledge it by responding with a 2xx complete, the server MUST acknowledge it by responding with a 2xx
(Successful) status code. Servers are RECOMMENDED to use a "201 (Successful) status code. Servers are RECOMMENDED to use a "201
(Created)" response if not otherwise specified. The response MUST (Created)" response if not otherwise specified. The response MUST
NOT include the "Upload-Complete" header field with the value set to NOT include the "Upload-Complete" 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. false.
If the request includes the "Upload-Complete" field value set to true If the request includes the "Upload-Complete" field value set to true
and a valid "Content-Length" header field, the client attempts to and a valid "Content-Length" header field, the client attempts to
upload the remaining resource in one request. In this case, the upload the remaining resource in one request. In this case, the
upload's final size is the sum of the upload's offset and 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 "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 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. 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 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 upload's final size. If they do not match, the server MUST reject
skipping to change at page 31, line 33 skipping to change at page 31, line 33
uploads. There are two options: - Use the standardized "Alt-Svc" uploads. There are two options: - Use the standardized "Alt-Svc"
response header field. However, it has been indicated to us that response header field. However, it has been indicated to us that
this header field might be reworked in the future and could also be this header field might be reworked in the future and could also be
semantically different from our intended usage. - Use a new response semantically different from our intended usage. - Use a new response
header field "Resumable-Uploads: https://example.org/files/*" to header field "Resumable-Uploads: https://example.org/files/*" to
indicate under which endpoints support for resumable uploads is indicate under which endpoints support for resumable uploads is
available. available.
*Send a 104 intermediate response to indicate support.* The clients *Send a 104 intermediate response to indicate support.* The clients
normally starts a traditional upload and includes a header field normally starts a traditional upload and includes a header field
indicate that it supports resumable uploads (e.g. "Upload-Offset: indicate that it supports resumable uploads (e.g. "Upload-Offset:
0"). If the server also supports resumable uploads, it will 0"). If the server also supports resumable uploads, it will
immediately respond with a 104 intermediate response to indicate its immediately respond with a 104 intermediate response to indicate its
support, before further processing the request. This way the client support, before further processing the request. This way the client
is informed during the upload whether it can resume from possible is informed during the upload whether it can resume from possible
connection errors or not. While an additional roundtrip is avoided, connection errors or not. While an additional roundtrip is avoided,
the problem with that solution is that many HTTP server libraries do the problem with that solution is that many HTTP server libraries do
not support sending custom 1XX responses and that some proxies may not support sending custom 1XX responses and that some proxies may
not be able to handle new 1XX status codes correctly. not be able to handle new 1XX status codes correctly.
*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 field indicating 103 code would then be accompanied by a header field indicating
support for resumable uploads (e.g. "Resumable-Uploads: 1"). It is support for resumable uploads (e.g. "Resumable-Uploads: 1"). It is
unclear whether the Early Hints code is appropriate for that, as it unclear whether the Early Hints code is appropriate for that, as it
is currently only used to indicate resources for prefetching them. is currently only used to indicate resources for prefetching them.
Appendix C. Upload Metadata Appendix C. Upload Metadata
When an upload is created (Section 4), the "Content-Type" and When an upload is created (Section 4), the "Content-Type" and
"Content-Disposition" header fields are allowed to be included. They "Content-Disposition" header fields are allowed to be included. They
are intended to be a standardized way of communicating the file name are intended to be a standardized way of communicating the file name
and file type, if available. However, this is not without and file type, if available. However, this is not without
controversy. Some argue that since these header fields are already controversy. Some argue that since these header fields are already
skipping to change at page 33, line 5 skipping to change at page 33, line 5
protocol. Members of the tus community helped significantly in the protocol. Members of the tus community helped significantly in the
process of bringing this work to the IETF. process of bringing this work to the IETF.
The authors would like to thank Mark Nottingham for substantive The authors would like to thank Mark Nottingham for substantive
contributions to the text. contributions to the text.
Changes Changes
This section is to be removed before publishing as an RFC. This section is to be removed before publishing as an RFC.
F.1. Since draft-ietf-httpbis-resumable-upload-04 F.1. Since draft-ietf-httpbis-resumable-upload-05
None yet
F.2. Since draft-ietf-httpbis-resumable-upload-04
o Clarify implications of "Upload-Limit" header. o Clarify implications of "Upload-Limit" header.
o Allow client to fetch upload limits upfront via "OPTIONS". o Allow client to fetch upload limits upfront via "OPTIONS".
o Add guidance on upload creation strategy. o Add guidance on upload creation strategy.
o Add "Upload-Length" header to indicate length during creation. o Add "Upload-Length" header to indicate length during creation.
o Describe possible usage of "Want-Repr-Digest". o Describe possible usage of "Want-Repr-Digest".
F.2. Since draft-ietf-httpbis-resumable-upload-03 F.3. Since draft-ietf-httpbis-resumable-upload-03
o Add note about "Content-Location" for referring to subsequent o Add note about "Content-Location" for referring to subsequent
resources. resources.
o Require "application/partial-upload" for appending to uploads. o Require "application/partial-upload" for appending to uploads.
o Explain handling of content and transfer codings. o Explain handling of content and transfer codings.
o Add problem types for mismatching offsets and completed uploads. o Add problem types for mismatching offsets and completed uploads.
o Clarify that completed uploads must not be appended to. o Clarify that completed uploads must not be appended to.
o Describe interaction with Digest Fields from RFC9530. o Describe interaction with Digest Fields from RFC9530.
o Require that upload offset does not decrease over time. o Require that upload offset does not decrease over time.
o Add Upload-Limit header field. o Add Upload-Limit header field.
o Increase the draft interop version. o Increase the draft interop version.
F.3. Since draft-ietf-httpbis-resumable-upload-02 F.4. Since draft-ietf-httpbis-resumable-upload-02
o Add upload progress notifications via informational responses. o Add upload progress notifications via informational responses.
o Add security consideration regarding request filtering. o Add security consideration regarding request filtering.
o Explain the use of empty requests for creation uploads and o Explain the use of empty requests for creation uploads and
appending. appending.
o Extend security consideration to include resource exhaustion o Extend security consideration to include resource exhaustion
attacks. attacks.
o Allow 200 status codes for offset retrieval. o Allow 200 status codes for offset retrieval.
o Increase the draft interop version. o Increase the draft interop version.
F.4. Since draft-ietf-httpbis-resumable-upload-01 F.5. Since draft-ietf-httpbis-resumable-upload-01
o Replace Upload-Incomplete header with Upload-Complete. o Replace Upload-Incomplete header with Upload-Complete.
o Replace terminology about procedures with HTTP resources. o Replace terminology about procedures with HTTP resources.
o Increase the draft interop version. o Increase the draft interop version.
F.5. Since draft-ietf-httpbis-resumable-upload-00 F.6. Since draft-ietf-httpbis-resumable-upload-00
o Remove Upload-Token and instead use Server-generated upload URL o Remove Upload-Token and instead use Server-generated upload URL
for upload identification. for upload identification.
o Require the Upload-Incomplete header field in Upload Creation o Require the Upload-Incomplete header field in Upload Creation
Procedure. Procedure.
o Increase the draft interop version. o Increase the draft interop version.
F.6. Since draft-tus-httpbis-resumable-uploads-protocol-02 F.7. Since draft-tus-httpbis-resumable-uploads-protocol-02
None None
F.7. Since draft-tus-httpbis-resumable-uploads-protocol-01 F.8. Since draft-tus-httpbis-resumable-uploads-protocol-01
o Clarifying backtracking and preventing skipping ahead during the o Clarifying backtracking and preventing skipping ahead during the
Offset Receiving Procedure. Offset Receiving Procedure.
o Clients auto-retry 404 is no longer allowed. o Clients auto-retry 404 is no longer allowed.
F.8. Since draft-tus-httpbis-resumable-uploads-protocol-00 F.9. Since draft-tus-httpbis-resumable-uploads-protocol-00
o Split the Upload Transfer Procedure into the Upload Creation o Split the Upload Transfer Procedure into the Upload Creation
Procedure and the Upload Appending Procedure. Procedure and the Upload Appending Procedure.
Authors' Addresses Authors' Addresses
Marius Kleidl (editor) Marius Kleidl (editor)
Transloadit Transloadit
Email: marius@transloadit.com Email: marius@transloadit.com
 End of changes. 17 change blocks. 
24 lines changed or deleted 29 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/