draft-ietf-httpbis-resumable-upload-03.txt | draft-ietf-httpbis-resumable-upload-04.txt | |||
---|---|---|---|---|
HTTP M. Kleidl, Ed. | HTTP M. Kleidl, Ed. | |||
Internet-Draft Transloadit | Internet-Draft Transloadit | |||
Intended status: Standards Track G. Zhang, Ed. | Intended status: Standards Track G. Zhang, Ed. | |||
Expires: 5 September 2024 Apple Inc. | Expires: 9 January 2025 Apple Inc. | |||
L. Pardue, Ed. | L. Pardue, Ed. | |||
Cloudflare | Cloudflare | |||
4 March 2024 | 8 July 2024 | |||
Resumable Uploads for HTTP | Resumable Uploads for HTTP | |||
draft-ietf-httpbis-resumable-upload-03 | draft-ietf-httpbis-resumable-upload-04 | |||
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 15 ¶ | skipping to change at page 2, line 15 ¶ | |||
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 5 September 2024. | This Internet-Draft will expire on 9 January 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 (https://trustee.ietf.org/ | Provisions Relating to IETF Documents (https://trustee.ietf.org/ | |||
license-info) in effect on the date of publication of this document. | license-info) in effect on the date of publication of this document. | |||
Please review these documents carefully, as they describe your rights | Please review these documents carefully, as they describe your rights | |||
and restrictions with respect to this document. Code Components | and restrictions with respect to this document. Code Components | |||
extracted from this document must include Revised BSD License text as | extracted from this document must include Revised BSD License text as | |||
described in Section 4.e of the Trust Legal Provisions and are | described in Section 4.e of the Trust Legal Provisions and are | |||
provided without warranty as described in the Revised BSD License. | provided without warranty as described in the Revised 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 . . . . . . . . . 7 | |||
4. Upload Creation . . . . . . . . . . . . . . . . . . . . . . . 7 | 4. Upload Creation . . . . . . . . . . . . . . . . . . . . . . . 8 | |||
4.1. Feature Detection . . . . . . . . . . . . . . . . . . . . 10 | 4.1. Feature Detection . . . . . . . . . . . . . . . . . . . . 11 | |||
4.2. Draft Version Identification . . . . . . . . . . . . . . 11 | 4.2. Draft Version Identification . . . . . . . . . . . . . . 11 | |||
5. Offset Retrieval . . . . . . . . . . . . . . . . . . . . . . 11 | 5. Offset Retrieval . . . . . . . . . . . . . . . . . . . . . . 12 | |||
6. Upload Append . . . . . . . . . . . . . . . . . . . . . . . . 13 | 6. Upload Append . . . . . . . . . . . . . . . . . . . . . . . . 13 | |||
7. Upload Cancellation . . . . . . . . . . . . . . . . . . . . . 15 | 7. Upload Cancellation . . . . . . . . . . . . . . . . . . . . . 16 | |||
8. Header Fields . . . . . . . . . . . . . . . . . . . . . . . . 16 | 8. Header Fields . . . . . . . . . . . . . . . . . . . . . . . . 17 | |||
8.1. Upload-Offset . . . . . . . . . . . . . . . . . . . . . . 16 | 8.1. Upload-Offset . . . . . . . . . . . . . . . . . . . . . . 17 | |||
8.2. Upload-Complete . . . . . . . . . . . . . . . . . . . . . 16 | 8.2. Upload-Limit . . . . . . . . . . . . . . . . . . . . . . 17 | |||
9. Redirection . . . . . . . . . . . . . . . . . . . . . . . . . 16 | 8.3. Upload-Complete . . . . . . . . . . . . . . . . . . . . . 18 | |||
10. Security Considerations . . . . . . . . . . . . . . . . . . . 16 | 9. Media Type application/partial-upload . . . . . . . . . . . . 18 | |||
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 | 10. Problem Types . . . . . . . . . . . . . . . . . . . . . . . . 18 | |||
12. References . . . . . . . . . . . . . . . . . . . . . . . . . 18 | 10.1. Mismatching Offset . . . . . . . . . . . . . . . . . . . 18 | |||
12.1. Normative References . . . . . . . . . . . . . . . . . . 18 | 10.2. Completed Upload . . . . . . . . . . . . . . . . . . . . 19 | |||
12.2. Informative References . . . . . . . . . . . . . . . . . 18 | 11. Offset values . . . . . . . . . . . . . . . . . . . . . . . . 19 | |||
12. Redirection . . . . . . . . . . . . . . . . . . . . . . . . . 20 | ||||
Appendix A. Informational Response . . . . . . . . . . . . . . . 18 | 13. Transfer and Content Codings . . . . . . . . . . . . . . . . 20 | |||
Appendix B. Feature Detection . . . . . . . . . . . . . . . . . 19 | 14. Integrity Digests . . . . . . . . . . . . . . . . . . . . . . 20 | |||
Appendix C. Upload Metadata . . . . . . . . . . . . . . . . . . 21 | 15. Subsequent Resources . . . . . . . . . . . . . . . . . . . . 21 | |||
Appendix D. FAQ . . . . . . . . . . . . . . . . . . . . . . . . 21 | 16. Security Considerations . . . . . . . . . . . . . . . . . . . 21 | |||
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 21 | 17. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 | |||
Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 | 18. References . . . . . . . . . . . . . . . . . . . . . . . . . 24 | |||
Since draft-ietf-httpbis-resumable-upload-02 . . . . . . . . . 22 | 18.1. Normative References . . . . . . . . . . . . . . . . . . 24 | |||
Since draft-ietf-httpbis-resumable-upload-01 . . . . . . . . . 22 | 18.2. Informative References . . . . . . . . . . . . . . . . . 24 | |||
Since draft-ietf-httpbis-resumable-upload-00 . . . . . . . . . 22 | Appendix A. Informational Response . . . . . . . . . . . . . . . 25 | |||
Since draft-tus-httpbis-resumable-uploads-protocol-02 . . . . . 23 | Appendix B. Feature Detection . . . . . . . . . . . . . . . . . 25 | |||
Since draft-tus-httpbis-resumable-uploads-protocol-01 . . . . . 23 | Appendix C. Upload Metadata . . . . . . . . . . . . . . . . . . 27 | |||
Since draft-tus-httpbis-resumable-uploads-protocol-00 . . . . . 23 | Appendix D. FAQ . . . . . . . . . . . . . . . . . . . . . . . . 28 | |||
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 23 | Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 28 | |||
Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 | ||||
Since draft-ietf-httpbis-resumable-upload-03 . . . . . . . . . 28 | ||||
Since draft-ietf-httpbis-resumable-upload-02 . . . . . . . . . 29 | ||||
Since draft-ietf-httpbis-resumable-upload-01 . . . . . . . . . 29 | ||||
Since draft-ietf-httpbis-resumable-upload-00 . . . . . . . . . 29 | ||||
Since draft-tus-httpbis-resumable-uploads-protocol-02 . . . . . 29 | ||||
Since draft-tus-httpbis-resumable-uploads-protocol-01 . . . . . 29 | ||||
Since draft-tus-httpbis-resumable-uploads-protocol-00 . . . . . 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 | |||
requests (see Section 14 of [HTTP]) support this concept of resumable | requests (see Section 14 of [HTTP]) support this concept of resumable | |||
skipping to change at page 5, line 22 ¶ | skipping to change at page 5, line 34 ¶ | |||
| 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 19 ¶ | skipping to change at page 8, line 37 ¶ | |||
append (Section 6), and upload cancellation (Section 7). | append (Section 6), and upload cancellation (Section 7). | |||
Once the upload resource is available and while the request content | Once the upload resource is available and while the request content | |||
is being uploaded, the target resource MAY send one or more | is being uploaded, the target resource MAY send one or more | |||
informational responses with a 104 (Upload Resumption Supported) | informational responses with a 104 (Upload Resumption Supported) | |||
status code to the client. In the first informational response, the | status code to the client. In the first informational response, the | |||
Location header field MUST be set to the URL pointing to the upload | Location header field MUST be set to the URL pointing to the upload | |||
resource. In subsequent informational responses, the Location header | resource. In subsequent informational responses, the Location header | |||
field MUST NOT be set. An informational response MAY contain the | field MUST NOT be set. An informational response MAY contain the | |||
Upload-Offset header field with the current upload offset as the | Upload-Offset header field with the current upload offset as the | |||
value to inform the client about the upload progress. In subsequent | value to inform the client about the upload progress. | |||
informational responses, the upload offset MUST NOT be smaller than | ||||
in previous informational responses. In addition, later offset | ||||
retrievals (Section 5) MUST NOT receive an upload offset that is less | ||||
than the offset reported in the latest informational response, | ||||
allowing the client to free associated resources. | ||||
The server MUST send the Upload-Offset header field in the response | The server MUST send the Upload-Offset header field in the response | |||
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 (e.g. | success (e.g. 201 (Created)), or when the response is a failure (e.g. | |||
409 (Conflict)). The Upload-Offset field value MUST be equal to the | 409 (Conflict)). The Upload-Offset field value MUST be equal to the | |||
end offset of the entire upload, or the begin offset of the next | end offset of the entire upload, or the begin offset of the next | |||
chunk if the upload is still incomplete. The client SHOULD consider | chunk if the upload is still incomplete. The client SHOULD consider | |||
the upload failed if the response has a status code that indicates a | the upload failed if the response has a status code that indicates a | |||
success but the offset indicated in the Upload-Offset field value | success but the offset indicated in the Upload-Offset field value | |||
does not equal the total of begin offset plus the number of bytes | does not equal the total of begin offset plus the number of bytes | |||
uploaded in the request. | 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 false | yet complete, as indicated by an Upload-Complete field value of false | |||
in the request, the server MUST acknowledge it by responding with the | in the request, the server MUST acknowledge it by responding with the | |||
201 (Created) status code and an Upload-Complete header value set to | 201 (Created) status code and an Upload-Complete header value set to | |||
false. | 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 server | upload's final size is the Content-Length field value and the server | |||
MUST record it to ensure its consistency. | MUST record it to ensure its consistency. | |||
The server MAY enforce a maximum size of an upload resource. This | ||||
limit MAY be equal to the upload's final size, if Upload-Complete: ?1 | ||||
and Content-Length are present in the upload creation request, or an | ||||
arbitrary value. The limit's value or its existence MUST NOT change | ||||
throughout the lifetime of the upload resource. The server MAY | ||||
indicate such a limit to the client by including the Upload-Limit | ||||
header field in the informational or final response to upload | ||||
creation. If the client receives an Upload-Limit header field | ||||
indicating that the maximum size is less than the amount of bytes it | ||||
intends to upload to a resource, it SHOULD stop the current upload | ||||
transfer immediately and cancel the upload (Section 7). | ||||
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 | If the server does not receive the entire request content, for | |||
the entire 100 bytes in the first request. The server generates two | example because of canceled requests or dropped connections, it | |||
informational responses to transmit the upload resource's URL and | SHOULD append as much of the request content starting at its | |||
progress information, and one final response to acknowledge the | beginning and without discontinuities as possible. If the server did | |||
completed upload: | not append the entire request content, the upload MUST NOT be | |||
considered complete. | ||||
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: 6 | |||
Upload-Complete: ?1 | Upload-Complete: ?1 | |||
Content-Length: 100 | Content-Length: 100 | |||
[content (100 bytes)] | [content (100 bytes)] | |||
HTTP/1.1 104 Upload Resumption Supported | HTTP/1.1 104 Upload Resumption Supported | |||
Upload-Draft-Interop-Version: 5 | Upload-Draft-Interop-Version: 6 | |||
Location: https://example.com/upload/b530ce8ff | Location: https://example.com/upload/b530ce8ff | |||
HTTP/1.1 104 Upload Resumption Supported | HTTP/1.1 104 Upload Resumption Supported | |||
Upload-Draft-Interop-Version: 5 | Upload-Draft-Interop-Version: 6 | |||
Upload-Offset: 50 | Upload-Offset: 50 | |||
HTTP/1.1 201 Created | HTTP/1.1 201 Created | |||
Location: https://example.com/upload/b530ce8ff | Location: https://example.com/upload/b530ce8ff | |||
Upload-Offset: 100 | Upload-Offset: 100 | |||
The next example shows an upload creation, where only the first 25 | The next example shows an upload creation, where only the first 25 | |||
bytes are transferred. The server acknowledges the received data and | bytes are transferred. The server acknowledges the received data and | |||
that the upload is not complete yet: | that the upload is not complete yet: | |||
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: 6 | |||
Upload-Complete: ?0 | Upload-Complete: ?0 | |||
Content-Length: 25 | Content-Length: 25 | |||
[partial content (25 bytes)] | [partial content (25 bytes)] | |||
HTTP/1.1 201 Created | HTTP/1.1 201 Created | |||
Location: https://example.com/upload/b530ce8ff | Location: https://example.com/upload/b530ce8ff | |||
Upload-Complete: ?0 | Upload-Complete: ?0 | |||
Upload-Offset: 25 | Upload-Offset: 25 | |||
Upload-Limit: max-size=1000000000 | ||||
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 coding of the representation is specified using | |||
the Content-Encoding header field and is retained throughout the | ||||
entire upload. When resuming an interrupted upload, the same content | ||||
coding is used for appending to the upload, producing a | ||||
representation of the upload resource with one consistent content | ||||
coding. 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.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. | |||
Servers SHOULD use the 104 (Upload Resumption Supported) | Servers SHOULD use the 104 (Upload Resumption Supported) | |||
informational response to indicate their support for a resumable | informational response to indicate their support for a resumable | |||
upload request. | upload request. | |||
Clients MUST NOT attempt to resume an upload unless they receive 104 | Clients MUST NOT attempt to resume an upload unless they receive 104 | |||
(Upload Resumption Supported) informational response, or have other | (Upload Resumption Supported) informational response, or have other | |||
out-of-band methods to determine server support for resumable | out-of-band methods to determine server support for resumable | |||
uploads. | uploads. | |||
4.2. Draft Version Identification | 4.2. Draft Version Identification | |||
*RFC Editor's Note:* Please remove this section and Upload-Draft- | *RFC Editor's Note:* Please remove this section and Upload-Draft- | |||
Interop-Version from all examples prior to publication of a final | Interop-Version from all examples prior to publication of a final | |||
version of this document. | version of this document. | |||
The current interop version is 5. | The current interop version is 6. | |||
Client implementations of draft versions of the protocol MUST send a | Client implementations of draft versions of the protocol MUST send a | |||
header field Upload-Draft-Interop-Version with the interop version as | header field Upload-Draft-Interop-Version with the interop version as | |||
its value to its requests. The Upload-Draft-Interop-Version field | its value to its requests. The Upload-Draft-Interop-Version field | |||
value is an Integer. | value is an Integer. | |||
Server implementations of draft versions of the protocol MUST NOT | Server implementations of draft versions of the protocol MUST NOT | |||
send a 104 (Upload Resumption Supported) informational response when | send a 104 (Upload Resumption Supported) informational response when | |||
the interop version indicated by the Upload-Draft-Interop-Version | the interop version indicated by the Upload-Draft-Interop-Version | |||
header field in the request is missing or mismatching. | header field in the request is missing or mismatching. | |||
skipping to change at page 12, line 10 ¶ | skipping to change at page 12, line 36 ¶ | |||
The request MUST NOT include an Upload-Offset or Upload-Complete | The request MUST NOT include an Upload-Offset or Upload-Complete | |||
header field. The server MUST reject requests with either of these | header field. The server MUST reject requests with either of these | |||
fields by responding with a 400 (Bad Request) status code. | fields by responding with a 400 (Bad Request) status code. | |||
If the server considers the upload resource to be active, it MUST | If the server considers the upload resource to be active, it MUST | |||
respond with a 204 (No Content) or 200 (OK) status code. The | respond with a 204 (No Content) or 200 (OK) status code. The | |||
response MUST include the Upload-Offset header field, with the value | response MUST include the Upload-Offset header field, with the value | |||
set to the current resumption offset for the target resource. The | set to the current resumption offset for the target resource. The | |||
response MUST include the Upload-Complete header field; the value is | response MUST include the Upload-Complete header field; the value is | |||
set to true only if the upload is complete. | set to true only if the upload is complete. The response MAY include | |||
the Upload-Limit header field if corresponding limits on the upload | ||||
resource exist. | ||||
An upload is considered complete only if the server completely and | An upload is considered complete only if the server completely and | |||
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 set | append request (Section 6) with the Upload-Complete header value set | |||
to true. | 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 request. | |||
request. | ||||
In order to prevent HTTP caching, the response SHOULD include a | In order to prevent HTTP caching, the response SHOULD include a | |||
Cache-Control header field with the value no-store. | 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 | |||
skipping to change at page 13, line 7 ¶ | skipping to change at page 13, line 32 ¶ | |||
the client cannot backtrack to the offset and reproduce the same | the client cannot backtrack to the offset and reproduce the same | |||
content it has already sent, the upload MUST be considered a failure. | content it has already sent, the upload MUST be considered a failure. | |||
The client MAY cancel the upload (Section 7) after rejecting the | The client MAY cancel the upload (Section 7) after rejecting the | |||
offset. | offset. | |||
The following example shows an offset retrieval request. The server | The following example shows an offset retrieval request. The server | |||
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: 6 | |||
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 with the application/partial- | |||
resource. The Upload-Offset field value (Section 8.1) MUST be set to | upload media type and MUST be sent to the upload resource. The | |||
the resumption offset. | Upload-Offset field value (Section 8.1) MUST be set 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 | |||
Upload-Complete field value (Section 8.2) 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) and ignore any representation metadata received | creation (Section 4). An upload append request continues uploading | |||
from appending (Section 6). | the same representation as used in the upload creation (Section 4) | |||
and thus uses the same content coding, if one was applied. For | ||||
example, if the initial upload creation included the Content- | ||||
Encoding: gzip header field, the upload append request resumes the | ||||
transfer of the gzipped data without indicating again that the gzip | ||||
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 code. | resource active, it MUST respond with a 404 (Not Found) status code. | |||
The client MUST NOT perform multiple upload transfers for the same | The client MUST NOT perform multiple upload transfers for the same | |||
upload resource in parallel. This helps avoid race conditions, and | upload resource in parallel. This helps avoid race conditions, and | |||
data loss or corruption. The server is RECOMMENDED to take measures | data loss or corruption. The server is RECOMMENDED to take measures | |||
to avoid parallel upload transfers: The server MAY terminate any | to avoid parallel upload transfers: The server MAY terminate any | |||
creation (Section 4) or append (Section 6) for the same upload URL. | creation (Section 4) or append for the same upload URL. Since the | |||
Since the client is not allowed to perform multiple transfers in | client is not allowed to perform multiple transfers in parallel, the | |||
parallel, the server can assume that the previous attempt has already | server can assume that the previous attempt has already failed. | |||
failed. Therefore, the server MAY abruptly terminate the previous | Therefore, the server MAY abruptly terminate the previous HTTP | |||
HTTP connection or stream. | connection or stream. | |||
If the offset indicated by the Upload-Offset field value does not | If the offset indicated by the Upload-Offset field value does not | |||
match the offset provided by the immediate previous offset retrieval | match the offset provided by the immediate previous offset retrieval | |||
(Section 5), or the end offset of the immediate previous incomplete | (Section 5), or the end offset of the immediate previous incomplete | |||
successful transfer, the server MUST respond with a 409 (Conflict) | successful transfer, the server MUST respond with a 409 (Conflict) | |||
status code. | status code. The server MAY use the problem type [PROBLEM] of | |||
"https://iana.org/assignments/http-problem-types#mismatching-upload- | ||||
offset" in the response; see Section 10.1. | ||||
The server applies the patch document of the application/partial- | ||||
upload media type by appending the request content to the targeted | ||||
upload resource. If the server does not receive the entire patch | ||||
document, for example because of canceled requests or dropped | ||||
connections, it SHOULD append as much of the patch document starting | ||||
at its beginning and without discontinuities as possible. Appending | ||||
a continuous section starting at the patch document's beginning | ||||
constitutes a successful PATCH as defined in Section 2 of [RFC5789]. | ||||
If the server did not receive and apply the entire patch document, | ||||
the upload MUST NOT be considered complete. | ||||
While the request content is being uploaded, the target resource MAY | While the request content is being uploaded, the target resource MAY | |||
send one or more informational responses with a 104 (Upload | send one or more informational responses with a 104 (Upload | |||
Resumption Supported) status code to the client. These informational | Resumption Supported) status code to the client. These informational | |||
responses MUST NOT contain the Location header field. They MAY | responses MUST NOT contain the Location header field. They MAY | |||
include the Upload-Offset header field with the current upload offset | include the Upload-Offset header field with the current upload offset | |||
as the value to inform the client about the upload progress. The | as the value to inform the client about the upload progress. | |||
same restrictions on the Upload-Offset header field in informational | ||||
responses from the upload creation (Section 4) apply. | ||||
The server MUST send the Upload-Offset header field in the response | The server MUST send the Upload-Offset header field in the response | |||
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 (e.g. | 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 of the | 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 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 status code indicates a success but the offset indicated by the | the status code indicates a success but the offset indicated by the | |||
Upload-Offset field value does not equal the total of begin offset | Upload-Offset field value does not equal the total of begin offset | |||
plus the number of bytes uploaded in the request. | plus the number of bytes uploaded in the request. | |||
If the upload is already complete, the server MUST NOT modify the | ||||
upload resource and MUST respond with a 400 (Bad Request) status | ||||
code. The server MAY use the problem type [PROBLEM] of | ||||
"https://iana.org/assignments/http-problem-types#completed-upload" in | ||||
the response; see Section 10.2. | ||||
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 NOT | |||
specified. The response MUST NOT include the Upload-Complete header | include the Upload-Complete header field with the value set to false. | |||
field with the value set to 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 12 ¶ | skipping to change at page 16, line 16 ¶ | |||
then set to true, the client wants to complete the upload without | then set to true, the client wants to complete the upload without | |||
appending additional data. | appending additional data. | |||
The following example shows an upload append. The client transfers | The following example shows an upload append. The client transfers | |||
the next 100 bytes at an offset of 100 and does not indicate that the | the next 100 bytes at an offset of 100 and does not indicate that the | |||
upload is then completed. The server acknowledges the new offset: | upload is then completed. The server acknowledges the new offset: | |||
PATCH /upload/b530ce8ff HTTP/1.1 | PATCH /upload/b530ce8ff HTTP/1.1 | |||
Host: example.com | Host: example.com | |||
Upload-Offset: 100 | Upload-Offset: 100 | |||
Upload-Draft-Interop-Version: 5 | Upload-Draft-Interop-Version: 6 | |||
Content-Length: 100 | Content-Length: 100 | |||
Content-Type: application/partial-upload | ||||
[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 16, line 12 ¶ | skipping to change at page 17, line 15 ¶ | |||
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. | |||
If the server does not support cancellation, it MUST respond with a | If the server does not support cancellation, it MUST respond with a | |||
405 (Method Not Allowed) status code. | 405 (Method Not Allowed) status code. | |||
The following example shows an upload cancellation: | The following example shows an upload cancellation: | |||
DELETE /upload/b530ce8ff HTTP/1.1 | DELETE /upload/b530ce8ff HTTP/1.1 | |||
Host: example.com | Host: example.com | |||
Upload-Draft-Interop-Version: 5 | Upload-Draft-Interop-Version: 6 | |||
HTTP/1.1 204 No Content | HTTP/1.1 204 No Content | |||
8. Header Fields | 8. Header Fields | |||
8.1. Upload-Offset | 8.1. Upload-Offset | |||
The Upload-Offset request and response header field indicates the | The Upload-Offset request and response header field indicates the | |||
resumption offset of corresponding upload, counted in bytes. The | resumption offset of corresponding upload, counted in bytes. The | |||
Upload-Offset field value is an Integer. | Upload-Offset field value is an Integer. | |||
8.2. Upload-Complete | 8.2. Upload-Limit | |||
The Upload-Limit response header field indicates limits applying the | ||||
upload resource. The Upload-Limit field value is a Dictionary. The | ||||
following limits are defined: | ||||
* The max-size key specifies a maximum size that an upload resource | ||||
is allowed to reach, counted in bytes. The value is an Integer. | ||||
* The min-size key specifies a minimum size for a resumable upload, | ||||
counted in bytes. The server will not create an upload resource | ||||
if the client indicates that the uploaded data is smaller than the | ||||
minimum size. The value is an Integer. | ||||
* The max-append-size key specifies a maximum size counted in bytes | ||||
for the request content in a single upload append request | ||||
(Section 6). The server MAY reject requests exceeding this limit | ||||
and a client SHOULD NOT send larger upload append requests. The | ||||
value is an Integer. | ||||
* The min-append-size key specifies a minimum size counted in bytes | ||||
for the request content in a single upload append request | ||||
(Section 6). The server MAY reject requests below this limit and | ||||
a client SHOULD NOT send smaller upload append requests. The | ||||
value is an Integer. | ||||
* The expires key specifies the remaining lifetime of the upload | ||||
resource in seconds counted from the generation of the response by | ||||
the server. After the resource's lifetime is reached, the server | ||||
MAY make the upload resource inaccessible and a client SHOULD NOT | ||||
attempt to access the upload resource. The lifetime MAY be | ||||
extended but SHOULD NOT be reduced once the upload resource is | ||||
created. The value is an Integer. | ||||
When parsing this header field, unrecognized keys MUST be ignored and | ||||
MUST NOT fail the parsing to facilitate the addition of new limits in | ||||
the future. | ||||
8.3. Upload-Complete | ||||
The Upload-Complete request and response header field indicates | The Upload-Complete request and response header field indicates | |||
whether the corresponding upload is considered complete. The Upload- | whether the corresponding upload is considered complete. The Upload- | |||
Complete field value is a Boolean. | Complete field value is a Boolean. | |||
The Upload-Complete header field MUST only be used if support by the | The Upload-Complete header field MUST only be used if support by the | |||
resource is known to the client (Section 4.1). | resource is known to the client (Section 4.1). | |||
9. Redirection | 9. Media Type application/partial-upload | |||
The application/partial-upload media type describes a contiguous | ||||
block of data that should be uploaded to a resource. There is no | ||||
minimum block size and the block might be empty. The start and end | ||||
of the block might align with the start and end of the file that | ||||
should be uploaded, but they are not required to be aligned. | ||||
10. Problem Types | ||||
10.1. Mismatching Offset | ||||
This section defines the "https://iana.org/assignments/http-problem- | ||||
types#mismatching-upload-offset" problem type [PROBLEM]. A server | ||||
MAY use this problem type when responding to an upload append request | ||||
(Section 6) to indicate that the Upload-Offset header field in the | ||||
request does not match the upload resource's offset. | ||||
Two problem type extension members are defined: the expected-offset | ||||
and provided-offset members. A response using this problem type | ||||
SHOULD populate both members, with the value of expected-offset taken | ||||
from the upload resource and the value of provided-offset taken from | ||||
the upload append request. | ||||
The following example shows an example response, where the resource's | ||||
offset was 100, but the client attempted to append at offset 200: | ||||
HTTP/1.1 409 Conflict | ||||
Content-Type: application/problem+json | ||||
{ | ||||
"type":"https://iana.org/assignments/http-problem-types#mismatching-upload-offset", | ||||
"title": "offset from request does not match offset of resource", | ||||
"expected-offset": 100, | ||||
"provided-offset": 200 | ||||
} | ||||
10.2. Completed Upload | ||||
This section defines the "https://iana.org/assignments/http-problem- | ||||
types#completed-upload" problem type [PROBLEM]. A server MAY use | ||||
this problem type when responding to an upload append request | ||||
(Section 6) to indicate that the upload has already been completed | ||||
and cannot be modified. | ||||
The following example shows an example response: | ||||
HTTP/1.1 400 Bad Request | ||||
Content-Type: application/problem+json | ||||
{ | ||||
"type":"https://iana.org/assignments/http-problem-types#completed-upload", | ||||
"title": "upload is already completed" | ||||
} | ||||
11. Offset values | ||||
The offset of an upload resource is the number of bytes that have | ||||
been appended to the upload resource. Appended data cannot be | ||||
removed from an upload and, therefore, the upload offset MUST NOT | ||||
decrease. A server MUST NOT generate responses containing an Upload- | ||||
Offset header field with a value that is smaller than was included in | ||||
previous responses for the same upload resource. This includes | ||||
informational and final responses for upload creation (Section 4), | ||||
upload appending (Section 6), and offset retrieval (Section 5). | ||||
If a server loses data that has been appended to an upload, it MUST | ||||
consider the upload resource invalid and reject further use of the | ||||
upload resource. The Upload-Offset header field in responses serves | ||||
as an acknowledgement of the append operation and as a guarantee that | ||||
no retransmission of the data will be necessary. Client can use this | ||||
guarantee to free resources associated to already uploaded data while | ||||
the upload is still ongoing. | ||||
12. Redirection | ||||
The 301 (Moved Permanently) and 302 (Found) status codes MUST NOT be | The 301 (Moved Permanently) and 302 (Found) status codes MUST NOT be | |||
used in offset retrieval (Section 5) and upload cancellation | 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 use | return a 308 (Permanent Redirect) status code and clients SHOULD use | |||
new permanent URI for subsequent requests. If the client receives a | new permanent URI for subsequent requests. If the client receives a | |||
307 (Temporary Redirect) response to an offset retrieval (Section 5) | 307 (Temporary Redirect) response to an offset retrieval (Section 5) | |||
request, it MAY apply the redirection directly in an immediate | request, it MAY apply the redirection directly in an immediate | |||
subsequent upload append (Section 6). | subsequent upload append (Section 6). | |||
10. Security Considerations | 13. Transfer and Content Codings | |||
A message might have a content coding, indicated by the Content- | ||||
Encoding header field, and/or a transfer coding, indicated by the | ||||
Transfer-Encoding header field (Section 6.1 of [HTTP/1.1]), applied, | ||||
which modify the representation of uploaded data in a message. For | ||||
correct interoperability, the client and server must share the same | ||||
logic when counting bytes for the upload offset. From the client's | ||||
perspective, the offset is counted after content coding but before | ||||
transfer coding is applied. From the server's perspective, the | ||||
offset is counted after the content's transfer coding is reversed but | ||||
before the content coding is reversed. | ||||
14. Integrity Digests | ||||
The integrity of an entire upload or individual upload requests can | ||||
be verifying using digests from [DIGEST-FIELDS]. | ||||
If the client knows the integrity digest of the entire data before | ||||
creating an upload resource, it MAY include the Repr-Digest header | ||||
field when creating an upload (Section 4). Once the upload is | ||||
completed, the server can compute the integrity digest of the | ||||
received upload representation and compare it to the provided digest. | ||||
If the digests don't match the server SHOULD consider the transfer | ||||
failed and not process the uploaded data further. This way, the | ||||
integrity of the entire uploaded data can be protected. | ||||
If the client knows the integrity digest of the content from an | ||||
upload creation (Section 4) or upload appending (Section 6) request, | ||||
it MAY include the Content-Digest header field in the request. Once | ||||
the content has been received, the server can compute the integrity | ||||
digest of the received content and compare it to the provided digest. | ||||
If the digests don't match the server SHOULD consider the transfer | ||||
failed and not append the content to the upload resource. This way, | ||||
the integrity of an individual request can be protected. | ||||
15. Subsequent Resources | ||||
The server might process the uploaded data and make its results | ||||
available in another resource during or after the upload. This | ||||
subsequent resource is different from the upload resource created by | ||||
the upload creation request (Section 4). The subsequent resource | ||||
does not handle the upload process itself, but instead facilitates | ||||
further interaction with the uploaded data. The server MAY indicate | ||||
the location of this subsequent resource by including the Content- | ||||
Location header field in informational or final responses generated | ||||
while creating (Section 4), appending to (Section 6), or retrieving | ||||
the offset (Section 5) of an upload. For example, a subsequent | ||||
resource could allow the client to fetch information extracted from | ||||
the uploaded data. | ||||
16. 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 17, line 29 ¶ | skipping to change at page 22, line 5 ¶ | |||
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. | |||
11. IANA Considerations | 17. 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.2 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 | | |||
+-----------------+-----------+------------------------------+ | +-----------------+-----------+------------------------------+ | |||
| Upload-Limit | permanent | Section 8.2 of this document | | ||||
+-----------------+-----------+------------------------------+ | ||||
Table 1 | Table 1 | |||
IANA is asked to register the following entry in the "HTTP Status | IANA is asked to register the following entry in the "HTTP Status | |||
Codes" registry: | Codes" registry: | |||
Value: 104 (suggested value) | Value: 104 (suggested value) | |||
Description: Upload Resumption Supported | Description: Upload Resumption Supported | |||
Specification: This document | Specification: This document | |||
12. References | IANA is asked to register the following entry in the "Media Types" | |||
registry: | ||||
12.1. Normative References | Type name: application | |||
Subtype name: partial-upload | ||||
Required parameters: N/A | ||||
Optional parameters: N/A | ||||
Encoding considerations: binary | ||||
Security considerations: see Section 16 of this document | ||||
Interoperability considerations: N/A | ||||
Published specification: This document | ||||
Applications that use this media type: Applications that transfer | ||||
files over unreliable networks or want pause- and resumable | ||||
uploads. | ||||
Fragment identifier considerations: N/A | ||||
Additional information: | ||||
* Deprecated alias names for this type: N/A | ||||
* Magic number(s): N/A | ||||
* File extension(s): N/A | ||||
* Macintosh file type code(s): N/A | ||||
* Windows Clipboard Name: N/A | ||||
Person and email address to contact for further information: See the | ||||
Authors' Addresses section of this document. | ||||
Intended usage: COMMON | ||||
Restrictions on usage: N/A | ||||
Author: See the Authors' Addresses section of this document. | ||||
Change controller: IETF | ||||
IANA is asked to register the following entry in the "HTTP Problem | ||||
Types" registry: | ||||
Type URI: https://iana.org/assignments/http-problem- | ||||
types#mismatching-upload-offset Title: | ||||
Mismatching Upload Offset Recommended HTTP status code: | ||||
409 Reference: | ||||
This document | ||||
IANA is asked to register the following entry in the "HTTP Problem | ||||
Types" registry: | ||||
Type URI: https://iana.org/assignments/http-problem-types#completed- | ||||
upload Title: | ||||
Upload Is Completed Recommended HTTP status code: | ||||
400 Reference: | ||||
This document | ||||
18. References | ||||
18.1. Normative References | ||||
[DIGEST-FIELDS] | ||||
Polli, R. and L. Pardue, "Digest Fields", RFC 9530, | ||||
DOI 10.17487/RFC9530, February 2024, | ||||
<https://www.rfc-editor.org/rfc/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/rfc/rfc9110>. | <https://www.rfc-editor.org/rfc/rfc9110>. | |||
[HTTP/1.1] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, | ||||
Ed., "HTTP/1.1", STD 99, RFC 9112, DOI 10.17487/RFC9112, | ||||
June 2022, <https://www.rfc-editor.org/rfc/rfc9112>. | ||||
[PROBLEM] Nottingham, M., Wilde, E., and S. Dalal, "Problem Details | ||||
for HTTP APIs", RFC 9457, DOI 10.17487/RFC9457, July 2023, | ||||
<https://www.rfc-editor.org/rfc/rfc9457>. | ||||
[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/rfc/rfc2119>. | <https://www.rfc-editor.org/rfc/rfc2119>. | |||
[RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", | ||||
RFC 5789, DOI 10.17487/RFC5789, March 2010, | ||||
<https://www.rfc-editor.org/rfc/rfc5789>. | ||||
[RFC6266] Reschke, J., "Use of the Content-Disposition Header Field | [RFC6266] Reschke, J., "Use of the Content-Disposition Header Field | |||
in the Hypertext Transfer Protocol (HTTP)", RFC 6266, | in the Hypertext Transfer Protocol (HTTP)", RFC 6266, | |||
DOI 10.17487/RFC6266, June 2011, | DOI 10.17487/RFC6266, June 2011, | |||
<https://www.rfc-editor.org/rfc/rfc6266>. | <https://www.rfc-editor.org/rfc/rfc6266>. | |||
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC | [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC | |||
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, | 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, | |||
May 2017, <https://www.rfc-editor.org/rfc/rfc8174>. | May 2017, <https://www.rfc-editor.org/rfc/rfc8174>. | |||
[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/rfc/rfc8941>. | <https://www.rfc-editor.org/rfc/rfc8941>. | |||
12.2. Informative References | 18.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/>. | |||
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) | |||
skipping to change at page 22, line 17 ¶ | skipping to change at page 28, line 32 ¶ | |||
design of this protocol. Members of the tus community helped | design of this protocol. Members of the tus community helped | |||
significantly in the process of bringing this work to the IETF. | significantly in the 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. | |||
Since draft-ietf-httpbis-resumable-upload-03 | ||||
* Add note about Content-Location for referring to subsequent | ||||
resources. | ||||
* Require application/partial-upload for appending to uploads. | ||||
* Explain handling of content and transfer codings. | ||||
* Add problem types for mismatching offsets and completed uploads. | ||||
* Clarify that completed uploads must not be appended to. | ||||
* Describe interaction with Digest Fields from RFC9530. | ||||
* Require that upload offset does not decrease over time. | ||||
* Add Upload-Limit header field. | ||||
* Increase the draft interop version. | ||||
Since draft-ietf-httpbis-resumable-upload-02 | Since draft-ietf-httpbis-resumable-upload-02 | |||
* Add upload progress notifications via informational responses. | * Add upload progress notifications via informational responses. | |||
* Add security consideration regarding request filtering. | * Add security consideration regarding request filtering. | |||
* Explain the use of empty requests for creation uploads and | * Explain the use of empty requests for creation uploads and | |||
appending. | appending. | |||
* Extend security consideration to include resource exhaustion | * Extend security consideration to include resource exhaustion | |||
End of changes. 50 change blocks. | ||||
105 lines changed or deleted | 425 lines changed or added | |||
This html diff was produced by rfcdiff 1.45. The latest version is available from http://tools.ietf.org/tools/rfcdiff/ |