draft-ietf-httpbis-resumable-upload-04.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: January 9, 2025 Apple Inc. | Expires: April 12, 2025 Apple Inc. | |||
L. Pardue, Ed. | L. Pardue, Ed. | |||
Cloudflare | Cloudflare | |||
July 08, 2024 | October 09, 2024 | |||
Resumable Uploads for HTTP | Resumable Uploads for HTTP | |||
draft-ietf-httpbis-resumable-upload-04 | 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 January 9, 2025. | This Internet-Draft will expire on April 12, 2025. | |||
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 2, line 34 ¶ | skipping to change at page 2, line 34 ¶ | |||
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. 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 . . . 5 | |||
3.2. Example 2: Upload as a series of parts . . . . . . . . . 6 | 3.2. Example 2: Upload as a series of parts . . . . . . . . . 6 | |||
4. Upload Creation . . . . . . . . . . . . . . . . . . . . . . . 7 | 4. Upload Creation . . . . . . . . . . . . . . . . . . . . . . . 7 | |||
4.1. Feature Detection . . . . . . . . . . . . . . . . . . . . 11 | 4.1. Feature Detection . . . . . . . . . . . . . . . . . . . . 11 | |||
4.2. Draft Version Identification . . . . . . . . . . . . . . 11 | 4.2. Draft Version Identification . . . . . . . . . . . . . . 11 | |||
5. Offset Retrieval . . . . . . . . . . . . . . . . . . . . . . 12 | 5. Offset Retrieval . . . . . . . . . . . . . . . . . . . . . . 12 | |||
6. Upload Append . . . . . . . . . . . . . . . . . . . . . . . . 13 | 6. Upload Append . . . . . . . . . . . . . . . . . . . . . . . . 13 | |||
7. Upload Cancellation . . . . . . . . . . . . . . . . . . . . . 16 | 7. Upload Cancellation . . . . . . . . . . . . . . . . . . . . . 16 | |||
8. Header Fields . . . . . . . . . . . . . . . . . . . . . . . . 17 | 8. Header Fields . . . . . . . . . . . . . . . . . . . . . . . . 17 | |||
8.1. Upload-Offset . . . . . . . . . . . . . . . . . . . . . . 17 | 8.1. Upload-Offset . . . . . . . . . . . . . . . . . . . . . . 17 | |||
8.2. Upload-Limit . . . . . . . . . . . . . . . . . . . . . . 17 | 8.2. Upload-Limit . . . . . . . . . . . . . . . . . . . . . . 17 | |||
8.3. Upload-Complete . . . . . . . . . . . . . . . . . . . . . 18 | 8.3. Upload-Complete . . . . . . . . . . . . . . . . . . . . . 18 | |||
9. Media Type application/partial-upload . . . . . . . . . . . . 18 | 9. Media Type application/partial-upload . . . . . . . . . . . . 18 | |||
10. Problem Types . . . . . . . . . . . . . . . . . . . . . . . . 18 | 10. Problem Types . . . . . . . . . . . . . . . . . . . . . . . . 18 | |||
10.1. Mismatching Offset . . . . . . . . . . . . . . . . . . . 18 | 10.1. Mismatching Offset . . . . . . . . . . . . . . . . . . . 18 | |||
10.2. Completed Upload . . . . . . . . . . . . . . . . . . . . 19 | 10.2. Completed Upload . . . . . . . . . . . . . . . . . . . . 19 | |||
11. Offset values . . . . . . . . . . . . . . . . . . . . . . . . 19 | 11. Offset values . . . . . . . . . . . . . . . . . . . . . . . . 19 | |||
12. Redirection . . . . . . . . . . . . . . . . . . . . . . . . . 20 | 12. Redirection . . . . . . . . . . . . . . . . . . . . . . . . . 20 | |||
13. Transfer and Content Codings . . . . . . . . . . . . . . . . 20 | 13. Content Codings . . . . . . . . . . . . . . . . . . . . . . . 20 | |||
14. Integrity Digests . . . . . . . . . . . . . . . . . . . . . . 20 | 14. Transfer Codings . . . . . . . . . . . . . . . . . . . . . . 20 | |||
15. Subsequent Resources . . . . . . . . . . . . . . . . . . . . 21 | 15. Integrity Digests . . . . . . . . . . . . . . . . . . . . . . 20 | |||
16. Security Considerations . . . . . . . . . . . . . . . . . . . 21 | 16. Subsequent Resources . . . . . . . . . . . . . . . . . . . . 21 | |||
17. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 | 17. Security Considerations . . . . . . . . . . . . . . . . . . . 21 | |||
18. References . . . . . . . . . . . . . . . . . . . . . . . . . 24 | 18. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 | |||
18.1. Normative References . . . . . . . . . . . . . . . . . . 24 | 19. References . . . . . . . . . . . . . . . . . . . . . . . . . 24 | |||
18.2. Informative References . . . . . . . . . . . . . . . . . 25 | 19.1. Normative References . . . . . . . . . . . . . . . . . . 24 | |||
19.2. Informative References . . . . . . . . . . . . . . . . . 25 | ||||
Appendix A. Informational Response . . . . . . . . . . . . . . . 25 | Appendix A. Informational Response . . . . . . . . . . . . . . . 25 | |||
Appendix B. Feature Detection . . . . . . . . . . . . . . . . . 25 | Appendix B. Feature Detection . . . . . . . . . . . . . . . . . 26 | |||
Appendix C. Upload Metadata . . . . . . . . . . . . . . . . . . 27 | Appendix C. Upload Metadata . . . . . . . . . . . . . . . . . . 28 | |||
Appendix D. FAQ . . . . . . . . . . . . . . . . . . . . . . . . 28 | Appendix D. FAQ . . . . . . . . . . . . . . . . . . . . . . . . 28 | |||
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 28 | Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 28 | |||
Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 | Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 | |||
F.1. Since draft-ietf-httpbis-resumable-upload-03 . . . . . . 28 | F.1. Since draft-ietf-httpbis-resumable-upload-04 . . . . . . 29 | |||
F.2. Since draft-ietf-httpbis-resumable-upload-02 . . . . . . 29 | F.2. Since draft-ietf-httpbis-resumable-upload-03 . . . . . . 29 | |||
F.3. Since draft-ietf-httpbis-resumable-upload-01 . . . . . . 29 | F.3. Since draft-ietf-httpbis-resumable-upload-02 . . . . . . 29 | |||
F.4. Since draft-ietf-httpbis-resumable-upload-00 . . . . . . 29 | F.4. Since draft-ietf-httpbis-resumable-upload-01 . . . . . . 29 | |||
F.5. Since draft-tus-httpbis-resumable-uploads-protocol-02 . . 29 | F.5. Since draft-ietf-httpbis-resumable-upload-00 . . . . . . 30 | |||
F.6. Since draft-tus-httpbis-resumable-uploads-protocol-01 . . 30 | F.6. Since draft-tus-httpbis-resumable-uploads-protocol-02 . . 30 | |||
F.7. Since draft-tus-httpbis-resumable-uploads-protocol-00 . . 30 | F.7. Since draft-tus-httpbis-resumable-uploads-protocol-01 . . 30 | |||
F.8. Since draft-tus-httpbis-resumable-uploads-protocol-00 . . 30 | ||||
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 30 | Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 30 | |||
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 4, line 31 ¶ | skipping to change at page 4, line 33 ¶ | |||
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, Token, Integer, and Boolean | The terms Byte Sequence, Item, String, Token, Integer, and Boolean | |||
are imported from [STRUCTURED-FIELDS]. | are imported from [STRUCTURED-FIELDS]. | |||
The terms client and server are from [HTTP]. | The terms "representation", "representation data", "representation | |||
metadata", "content", "client" and "server" are from [HTTP]. | ||||
3. Overview | 3. Overview | |||
Resumable uploads are supported in HTTP through use of a temporary | Resumable uploads are supported in HTTP through use of a temporary | |||
resource, an _upload resource_, that is separate from the resource | resource, an _upload resource_, that is separate from the resource | |||
being uploaded to (hereafter, the _target resource_) and specific to | being uploaded to (hereafter, the _target resource_) and specific to | |||
that upload. By interacting with the upload resource, a client can | that upload. By interacting with the upload resource, a client can | |||
retrieve the current offset of the upload (Section 5), append to the | retrieve the current offset of the upload (Section 5), append to the | |||
upload (Section 6), and cancel the upload (Section 7). | upload (Section 6), and cancel the upload (Section 7). | |||
skipping to change at page 10, line 45 ¶ | skipping to change at page 10, line 45 ¶ | |||
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 media type of the | (Section 8.3 of [HTTP]) can be used to indicate the media type of the | |||
file. The content coding of the representation is specified using | file. The applied content codings are specified using the "Content- | |||
the "Content-Encoding" header field and is retained throughout the | Encoding" header field and are retained throughout the entire upload. | |||
entire upload. When resuming an interrupted upload, the same content | When resuming an interrupted upload, the same content codings are | |||
coding is used for appending to the upload, producing a | used for appending to the upload, producing a representation of the | |||
representation of the upload resource with one consistent content | upload resource. The "Content-Disposition" header field ([RFC6266]) | |||
coding. The "Content-Disposition" header field ([RFC6266]) can be | can be used to transmit a filename; if included, the parameters | |||
used to transmit a filename; if included, the parameters SHOULD be | SHOULD be either "filename", "filename*" or "boundary". | |||
either "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.3) MUST NOT be false if the server support is | value (Section 8.3) MUST NOT be false if the server support is | |||
unclear. This allows the upload to function as if it is a regular | unclear. This allows the upload to function as if it is a regular | |||
upload. | upload. | |||
skipping to change at page 13, line 5 ¶ | skipping to change at page 12, line 50 ¶ | |||
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's 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 request. | the resumption offset from a single offset retrieving request. | |||
In order to prevent HTTP caching, the response SHOULD include a | In order to prevent HTTP caching ([CACHING]), the response SHOULD | |||
"Cache-Control" header field with the value "no-store". | include a "Cache-Control" header field with the value "no-store". | |||
If the server does not consider the upload resource to be active, it | If the server does not consider the upload resource to be active, it | |||
MUST respond with a "404 (Not Found)" status code. | MUST respond with a "404 (Not Found)" status 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 | |||
skipping to change at page 13, line 51 ¶ | skipping to change at page 13, line 48 ¶ | |||
partial-upload" media type and MUST be sent to the upload resource. | partial-upload" media type and MUST be sent to the upload resource. | |||
The "Upload-Offset" field value (Section 8.1) MUST be set to the | The "Upload-Offset" field value (Section 8.1) MUST be set to the | |||
resumption offset. | 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 | |||
"Upload-Complete" field value (Section 8.3) MUST be set to false. | "Upload-Complete" field value (Section 8.3) MUST be set to false. | |||
The server SHOULD respect representation metadata received during | The server SHOULD respect representation metadata received during | |||
creation (Section 4). An upload append request continues uploading | creation (Section 4). An upload append request continues uploading | |||
the same representation as used in the upload creation (Section 4) | the same representation as used in the upload creation (Section 4) | |||
and thus uses the same content coding, if one was applied. For | and thus uses the same content codings, if they were applied. For | |||
example, if the initial upload creation included the "Content- | example, if the initial upload creation included the "Content- | |||
Encoding: gzip" header field, the upload append request resumes the | Encoding: gzip" header field, the upload append request resumes the | |||
transfer of the gzipped data without indicating again that the gzip | transfer of the gzipped data without indicating again that the gzip | |||
coding is applied. | coding is applied. | |||
If the server does not consider the upload associated with the upload | If the server does not consider the upload associated with the upload | |||
resource active, it MUST respond with a "404 (Not Found)" status | resource active, it MUST respond with a "404 (Not Found)" status | |||
code. | code. | |||
The client MUST NOT perform multiple upload transfers for the same | The client MUST NOT perform multiple upload transfers for the same | |||
skipping to change at page 20, line 11 ¶ | skipping to change at page 20, line 11 ¶ | |||
guarantee that no retransmission of the data will be necessary. | guarantee that no retransmission of the data will be necessary. | |||
Client can use this guarantee to free resources associated to already | Client can use this guarantee to free resources associated to already | |||
uploaded data while the upload is still ongoing. | uploaded data while the upload is still ongoing. | |||
12. Redirection | 12. Redirection | |||
The "301 (Moved Permanently)" and "302 (Found)" status codes MUST NOT | The "301 (Moved Permanently)" and "302 (Found)" status codes MUST NOT | |||
be used in offset retrieval (Section 5) and upload cancellation | be used in offset retrieval (Section 5) and upload cancellation | |||
(Section 7) responses. For other responses, the upload resource MAY | (Section 7) responses. For other responses, the upload resource MAY | |||
return a "308 (Permanent Redirect)" status code and clients SHOULD | return a "308 (Permanent Redirect)" status code and clients SHOULD | |||
use new permanent URI for subsequent requests. If the client | use the new permanent URI for subsequent requests. If the client | |||
receives a "307 (Temporary Redirect)" response to an offset retrieval | receives a "307 (Temporary Redirect)" response to an offset retrieval | |||
(Section 5) request, it MAY apply the redirection directly in an | (Section 5) request, it MAY apply the redirection directly in an | |||
immediate subsequent upload append (Section 6). | immediate subsequent upload append (Section 6). | |||
13. Transfer and Content Codings | 13. Content Codings | |||
A message might have a content coding, indicated by the "Content- | Since the codings listed in "Content-Encoding" are a characteristic | |||
Encoding" header field, and/or a transfer coding, indicated by the | of the representation (see Section 8.4 of [HTTP]), both the client | |||
"Transfer-Encoding" header field (Section 6.1 of [RFC9112]), applied, | and the server always compute the upload offset on the content coded | |||
which modify the representation of uploaded data in a message. For | data (that is, the representation data). Moreover, the content | |||
correct interoperability, the client and server must share the same | codings are retained throughout the entire upload, meaning thats that | |||
logic when counting bytes for the upload offset. From the client's | the server is not required to decode the representation data to | |||
perspective, the offset is counted after content coding but before | support resumable uploads. See Appendix A of [DIGEST-FIELDS] for | |||
transfer coding is applied. From the server's perspective, the | more information. | |||
offset is counted after the content's transfer coding is reversed but | ||||
before the content coding is reversed. | ||||
14. Integrity Digests | 14. Transfer Codings | |||
Unlike "Content-Encoding" (see Section 8.4.1 of [HTTP]), "Transfer- | ||||
Encoding" (see Section 6.1 of [RFC9112]) is a property of the | ||||
message, not of the representation. Moreover. transfer codings can | ||||
be applied in transit (e.g., by proxies). This means that a client | ||||
does not have to consider the transfer codings to compute the upload | ||||
offset, while a server is responsible for transfer decoding the | ||||
message before computing the upload offset. Please note that the | ||||
"Content-Length" header field cannot be used in conjunction with the | ||||
"Transfer-Encoding" header field. | ||||
15. Integrity Digests | ||||
The integrity of an entire upload or individual upload requests can | The integrity of an entire upload or individual upload requests can | |||
be verifying using digests from [DIGEST-FIELDS]. | be verifying using digests from [DIGEST-FIELDS]. | |||
If the client knows the integrity digest of the entire data before | If the client knows the integrity digest of the entire data before | |||
creating an upload resource, it MAY include the "Repr-Digest" header | creating an upload resource, it MAY include the "Repr-Digest" header | |||
field when creating an upload (Section 4). Once the upload is | field when creating an upload (Section 4). Once the upload is | |||
completed, the server can compute the integrity digest of the | completed, the server can compute the integrity digest of the | |||
received upload representation and compare it to the provided digest. | received upload representation and compare it to the provided digest. | |||
If the digests don't match the server SHOULD consider the transfer | If the digests don't match the server SHOULD consider the transfer | |||
skipping to change at page 21, line 5 ¶ | skipping to change at page 21, line 15 ¶ | |||
If the client knows the integrity digest of the content from an | If the client knows the integrity digest of the content from an | |||
upload creation (Section 4) or upload appending (Section 6) request, | upload creation (Section 4) or upload appending (Section 6) request, | |||
it MAY include the "Content-Digest" header field in the request. | it MAY include the "Content-Digest" header field in the request. | |||
Once the content has been received, the server can compute the | Once the content has been received, the server can compute the | |||
integrity digest of the received content and compare it to the | integrity digest of the received content and compare it to the | |||
provided digest. If the digests don't match the server SHOULD | provided digest. If the digests don't match the server SHOULD | |||
consider the transfer failed and not append the content to the upload | consider the transfer failed and not append the content to the upload | |||
resource. This way, the integrity of an individual request can be | resource. This way, the integrity of an individual request can be | |||
protected. | protected. | |||
15. Subsequent Resources | 16. Subsequent Resources | |||
The server might process the uploaded data and make its results | The server might process the uploaded data and make its results | |||
available in another resource during or after the upload. This | available in another resource during or after the upload. This | |||
subsequent resource is different from the upload resource created by | subsequent resource is different from the upload resource created by | |||
the upload creation request (Section 4). The subsequent resource | the upload creation request (Section 4). The subsequent resource | |||
does not handle the upload process itself, but instead facilitates | does not handle the upload process itself, but instead facilitates | |||
further interaction with the uploaded data. The server MAY indicate | further interaction with the uploaded data. The server MAY indicate | |||
the location of this subsequent resource by including the "Content- | the location of this subsequent resource by including the "Content- | |||
Location" header field in informational or final responses generated | Location" header field in the informational or final responses | |||
while creating (Section 4), appending to (Section 6), or retrieving | generated while creating (Section 4), appending to (Section 6), or | |||
the offset (Section 5) of an upload. For example, a subsequent | retrieving the offset (Section 5) of an upload. For example, a | |||
resource could allow the client to fetch information extracted from | subsequent resource could allow the client to fetch information | |||
the uploaded data. | extracted from the uploaded data. | |||
16. Security Considerations | 17. Security Considerations | |||
The upload resource URL is the identifier used for modifying the | The upload resource URL is the identifier used for modifying the | |||
upload. Without further protection of this URL, an attacker may | upload. Without further protection of this URL, an attacker may | |||
obtain information about an upload, append data to it, or cancel it. | obtain information about an upload, append data to it, or cancel it. | |||
To prevent this, the server SHOULD ensure that only authorized | To prevent this, the server SHOULD ensure that only authorized | |||
clients can access the upload resource. In addition, the upload | clients can access the upload resource. In addition, the upload | |||
resource URL SHOULD be generated in such a way that makes it hard to | resource URL SHOULD be generated in such a way that makes it hard to | |||
be guessed by unauthorized clients. | be guessed by unauthorized clients. | |||
Some servers or intermediaries provide scanning of content uploaded | Some servers or intermediaries provide scanning of content uploaded | |||
skipping to change at page 22, line 5 ¶ | skipping to change at page 22, line 15 ¶ | |||
server resources by creating and holding open uploads indefinitely | server resources by creating and holding open uploads indefinitely | |||
with minimal work. | with minimal work. | |||
Servers SHOULD provide mitigations for Slowloris attacks, such as | Servers SHOULD provide mitigations for Slowloris attacks, such as | |||
increasing the maximum number of clients the server will allow, | increasing the maximum number of clients the server will allow, | |||
limiting the number of uploads a single client is allowed to make, | limiting the number of uploads a single client is allowed to make, | |||
imposing restrictions on the minimum transfer speed an upload is | imposing restrictions on the minimum transfer speed an upload is | |||
allowed to have, and restricting the length of time an upload | allowed to have, and restricting the length of time an upload | |||
resource can exist. | resource can exist. | |||
17. IANA Considerations | 18. IANA Considerations | |||
IANA is asked to register the following entries in the "Hypertext | IANA is asked to register the following entries in the "Hypertext | |||
Transfer Protocol (HTTP) Field Name Registry": | Transfer Protocol (HTTP) Field Name Registry": | |||
+-----------------+-----------+------------------------------+ | +-----------------+-----------+------------------------------+ | |||
| Field Name | Status | Reference | | | Field Name | Status | Reference | | |||
+-----------------+-----------+------------------------------+ | +-----------------+-----------+------------------------------+ | |||
| Upload-Complete | permanent | Section 8.3 of this document | | | Upload-Complete | permanent | Section 8.3 of this document | | |||
| | | | | | | | | | |||
| Upload-Offset | permanent | Section 8.1 of this document | | | Upload-Offset | permanent | Section 8.1 of this document | | |||
skipping to change at page 22, line 41 ¶ | skipping to change at page 23, line 4 ¶ | |||
Type name: application | Type name: application | |||
Subtype name: partial-upload | Subtype name: partial-upload | |||
Required parameters: N/A | Required parameters: N/A | |||
Optional parameters: N/A | Optional parameters: N/A | |||
Encoding considerations: binary | Encoding considerations: binary | |||
Security considerations: see Section 17 of this document | ||||
Security considerations: see Section 16 of this document | ||||
Interoperability considerations: N/A | Interoperability considerations: N/A | |||
Published specification: This document | Published specification: This document | |||
Applications that use this media type: Applications that transfer | Applications that use this media type: Applications that transfer | |||
files over unreliable networks or want pause- and resumable | files over unreliable networks or want pause- and resumable | |||
uploads. | uploads. | |||
Fragment identifier considerations: N/A | Fragment identifier considerations: N/A | |||
skipping to change at page 24, line 5 ¶ | skipping to change at page 24, line 17 ¶ | |||
Type URI: https://iana.org/assignments/http-problem-types#completed- | Type URI: https://iana.org/assignments/http-problem-types#completed- | |||
upload Title: | upload Title: | |||
Upload Is Completed Recommended HTTP status code: | Upload Is Completed Recommended HTTP status code: | |||
400 Reference: | 400 Reference: | |||
This document | This document | |||
18. References | 19. References | |||
18.1. Normative References | 19.1. Normative References | |||
[CACHING] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, | ||||
Ed., "HTTP Caching", STD 98, RFC 9111, | ||||
DOI 10.17487/RFC9111, June 2022, | ||||
<https://www.rfc-editor.org/info/rfc9111>. | ||||
[DIGEST-FIELDS] | [DIGEST-FIELDS] | |||
Polli, R. and L. Pardue, "Digest Fields", RFC 9530, | Polli, R. and L. Pardue, "Digest Fields", RFC 9530, | |||
DOI 10.17487/RFC9530, February 2024, | DOI 10.17487/RFC9530, February 2024, | |||
<https://www.rfc-editor.org/info/rfc9530>. | <https://www.rfc-editor.org/info/rfc9530>. | |||
[HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, | [HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, | |||
Ed., "HTTP Semantics", STD 97, RFC 9110, | Ed., "HTTP Semantics", STD 97, RFC 9110, | |||
DOI 10.17487/RFC9110, June 2022, | DOI 10.17487/RFC9110, June 2022, | |||
<https://www.rfc-editor.org/info/rfc9110>. | <https://www.rfc-editor.org/info/rfc9110>. | |||
skipping to change at page 25, line 5 ¶ | skipping to change at page 25, line 18 ¶ | |||
[RFC9112] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, | [RFC9112] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, | |||
Ed., "HTTP/1.1", STD 99, RFC 9112, DOI 10.17487/RFC9112, | Ed., "HTTP/1.1", STD 99, RFC 9112, DOI 10.17487/RFC9112, | |||
June 2022, <https://www.rfc-editor.org/info/rfc9112>. | June 2022, <https://www.rfc-editor.org/info/rfc9112>. | |||
[STRUCTURED-FIELDS] | [STRUCTURED-FIELDS] | |||
Nottingham, M. and P. 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>. | |||
18.2. Informative References | 19.2. Informative References | |||
[SLOWLORIS] | [SLOWLORIS] | |||
"RSnake" Hansen, R., "Welcome to Slowloris - the low | "RSnake" Hansen, R., "Welcome to Slowloris - the low | |||
bandwidth, yet greedy and poisonous HTTP client!", June | bandwidth, yet greedy and poisonous HTTP client!", June | |||
2009, <https://web.archive.org/web/20150315054838/ | 2009, <https://web.archive.org/web/20150315054838/ | |||
http://ha.ckers.org/slowloris/>. | http://ha.ckers.org/slowloris/>. | |||
18.3. URIs | 19.3. URIs | |||
[1] https://tus.io/ | [1] https://tus.io/ | |||
Appendix A. Informational Response | Appendix A. Informational Response | |||
The server is allowed to respond to upload creation (Section 4) | The server is allowed to respond to upload creation (Section 4) | |||
requests with a "104 (Upload Resumption Supported)" intermediate | requests with a "104 (Upload Resumption Supported)" intermediate | |||
response as soon as the server has validated the request. This way, | response as soon as the server has validated the request. This way, | |||
the client knows that the server supports resumable uploads before | the client knows that the server supports resumable uploads before | |||
the complete response is received. The benefit is the clients can | the complete response is received. The benefit is the clients can | |||
skipping to change at page 28, line 38 ¶ | skipping to change at page 29, 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-03 | F.1. Since draft-ietf-httpbis-resumable-upload-04 | |||
None yet | ||||
F.2. 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.2. Since draft-ietf-httpbis-resumable-upload-02 | F.3. 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.3. Since draft-ietf-httpbis-resumable-upload-01 | F.4. 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.4. Since draft-ietf-httpbis-resumable-upload-00 | F.5. 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.5. Since draft-tus-httpbis-resumable-uploads-protocol-02 | F.6. Since draft-tus-httpbis-resumable-uploads-protocol-02 | |||
None | None | |||
F.6. Since draft-tus-httpbis-resumable-uploads-protocol-01 | F.7. 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.7. Since draft-tus-httpbis-resumable-uploads-protocol-00 | F.8. 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. 32 change blocks. | ||||
68 lines changed or deleted | 88 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/ |