idnits 2.17.1 draft-tus-httpbis-resumable-uploads-protocol-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == There are 4 instances of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (24 February 2022) is 792 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Normative reference to a draft: ref. 'HTTP' Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTP M. Kleidl 3 Internet-Draft Transloadit Ltd 4 Intended status: Standards Track J. Mehta 5 Expires: 28 August 2022 G. Zhang 6 Apple Inc. 7 L. Pardue 8 Cloudflare 9 S. Matsson 10 JellyHive 11 24 February 2022 13 tus - Resumable Uploads Protocol 14 draft-tus-httpbis-resumable-uploads-protocol-00 16 Abstract 18 HTTP clients often encounter interrupted data transfers as a result 19 of canceled requests or dropped connections. Prior to interruption, 20 part of a representation may have been exchanged. To complete the 21 data transfer of the entire representation, it is often desirable to 22 issue subsequent requests that transfer only the remainder of the 23 representation. HTTP range requests support this concept of 24 resumable downloads from server to client. This document describes a 25 mechanism that supports resumable uploads from client to server using 26 HTTP. 28 Discussion Venues 30 This note is to be removed before publishing as an RFC. 32 Discussion of this document takes place on the tus-v2 GitHub 33 repository at https://github.com/tus/tus-v2. 35 Status of This Memo 37 This Internet-Draft is submitted in full conformance with the 38 provisions of BCP 78 and BCP 79. 40 Internet-Drafts are working documents of the Internet Engineering 41 Task Force (IETF). Note that other groups may also distribute 42 working documents as Internet-Drafts. The list of current Internet- 43 Drafts is at https://datatracker.ietf.org/drafts/current/. 45 Internet-Drafts are draft documents valid for a maximum of six months 46 and may be updated, replaced, or obsoleted by other documents at any 47 time. It is inappropriate to use Internet-Drafts as reference 48 material or to cite them other than as "work in progress." 49 This Internet-Draft will expire on 28 August 2022. 51 Copyright Notice 53 Copyright (c) 2022 IETF Trust and the persons identified as the 54 document authors. All rights reserved. 56 This document is subject to BCP 78 and the IETF Trust's Legal 57 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 58 license-info) in effect on the date of publication of this document. 59 Please review these documents carefully, as they describe your rights 60 and restrictions with respect to this document. Code Components 61 extracted from this document must include Revised BSD License text as 62 described in Section 4.e of the Trust Legal Provisions and are 63 provided without warranty as described in the Revised BSD License. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 68 2. Conventions and Definitions . . . . . . . . . . . . . . . . . 3 69 3. Uploading Overview . . . . . . . . . . . . . . . . . . . . . 4 70 3.1. Example 1: Complete upload of file with known size . . . 4 71 3.2. Example 2: Upload as a series of parts . . . . . . . . . 6 72 4. Upload Transfer Procedure . . . . . . . . . . . . . . . . . . 7 73 4.1. Feature Detection . . . . . . . . . . . . . . . . . . . . 10 74 4.2. Draft Version Identification . . . . . . . . . . . . . . 10 75 5. Offset Retrieving Procedure . . . . . . . . . . . . . . . . . 11 76 6. Upload Cancellation Procedure . . . . . . . . . . . . . . . . 12 77 7. Header Fields . . . . . . . . . . . . . . . . . . . . . . . . 13 78 7.1. Upload-Token . . . . . . . . . . . . . . . . . . . . . . 13 79 7.2. Upload-Offset . . . . . . . . . . . . . . . . . . . . . . 13 80 7.3. Upload-Incomplete . . . . . . . . . . . . . . . . . . . . 14 81 8. Redirection . . . . . . . . . . . . . . . . . . . . . . . . . 14 82 9. Security Considerations . . . . . . . . . . . . . . . . . . . 14 83 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 84 11. Normative References . . . . . . . . . . . . . . . . . . . . 15 85 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 15 86 Appendix . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 87 Informational Response . . . . . . . . . . . . . . . . . . . . 16 88 Feature Detection . . . . . . . . . . . . . . . . . . . . . . . 16 89 Upload Metadata . . . . . . . . . . . . . . . . . . . . . . . . 18 90 FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 91 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 19 93 1. Introduction 95 HTTP clients often encounter interrupted data transfers as a result 96 of canceled requests or dropped connections. Prior to interruption, 97 part of a representation (see Section 3.2 of [HTTP]) might have been 98 exchanged. To complete the data transfer of the entire 99 representation, it is often desirable to issue subsequent requests 100 that transfer only the remainder of the representation. HTTP range 101 requests (see Section 14 of [HTTP]) support this concept of resumable 102 downloads from server to client. 104 HTTP methods such as POST or PUT can be used by clients to request 105 processing of representation data enclosed in the request message. 106 The transfer of representation data from client to server is often 107 referred to as an upload. Uploads are just as likely as downloads to 108 suffer from the effects of data transfer interruption. Humans can 109 play a role in upload interruptions through manual actions such as 110 pausing an upload. Regardless of the cause of an interruption, 111 servers may have received part of the representation before its 112 occurrence and it is desirable if clients can complete the data 113 transfer by sending only the remainder of the representation. The 114 process of sending additional parts of a representation using 115 subsequent HTTP requests from client to server is herein referred to 116 as a resumable upload. 118 Connection interruptions are common and the absence of a standard 119 mechanism for resumable uploads has lead to a proliferation of custom 120 solutions. Some of those use HTTP, while others rely on other 121 transfer mechanisms entirely. An HTTP-based standard solution is 122 desirable for such a common class of problem. 124 This document defines the Resumable Uploads Protocol, an optional 125 mechanism for resumable uploads using HTTP that is backwards- 126 compatible with conventional HTTP uploads. When an upload is 127 interrupted, clients can send subsequent requests to query the server 128 state and use this information to the send remaining data. 129 Alternatively, they can cancel the upload entirely. 131 2. Conventions and Definitions 133 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 134 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 135 "OPTIONAL" in this document are to be interpreted as described in 136 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 137 capitals, as shown here. 139 The terms byte sequence, Item, string, sf-binary, sf-boolean, sf- 140 integer, sf-string, and sf-token are imported from 141 [STRUCTURED-FIELDS]. 143 The terms client and server are imported from [HTTP]. 145 Upload: A sequence of one or more procedures, uniquely identified by 146 a token chosen by a client. 148 Procedure: An HTTP message exchange for that can be used for 149 resumable uploads. 151 3. Uploading Overview 153 The Resumable Uploads Protocol consists of several procedures that 154 rely on HTTP message exchanges. The following procedures are 155 defined: 157 * Upload Transfer Procedure (Section 4) 159 * Offset Retrieving Procedure (Section 5) 161 * Upload Cancellation Procedure (Section 6) 163 A single upload is a sequence of one or more procedures. Each upload 164 is uniquely identified by a token chosen by a client. The token is 165 carried in the Upload-Token header field; see Section 7.1. 167 The remainder of this section uses examples of a file upload to 168 illustrate permutations of procedure sequence. Note, however, that 169 HTTP message exchanges use representation data (see Section 8.1 of 170 [HTTP]), which means that procedures can apply to many forms of 171 content. 173 3.1. Example 1: Complete upload of file with known size 175 In this example, the client first attempts to upload a file with a 176 known size in a single HTTP request. An interruption occurs and the 177 client then attempts to resume the upload using subsequent HTTP 178 requests. 180 1) The Upload Transfer Procedure (Section 4) can be used to notify 181 the server that the client wants to begin an upload. The server 182 should then reserve the required resources to accept the upload from 183 the client. The client also begins transferring the entire file in 184 the request body. The request includes the Upload-Token header, 185 which is used for identifying future requests related to this upload. 186 An informational response can be sent to the client to signal the 187 support of resumable upload on the server. 189 Client Server 190 | | 191 | POST with Upload-Token | 192 |------------------------------------------->| 193 | | 194 | | Reserve resources 195 | | for Upload-Token 196 | |------------------ 197 | | | 198 | |<----------------- 199 | | 200 | 104 Upload Resumption Supported | 201 |<-------------------------------------------| 202 | | 203 | Flow Interrupted | 204 |------------------------------------------->| 205 | | 207 Figure 1: Upload Transfer Procedure Initiation 209 2) If the connection to the server gets interrupted during the Upload 210 Transfer Procedure, the client may want to resume the upload. Before 211 this is possible, the client must know the amount of data that the 212 server was able to receive before the connection got interrupted. To 213 achieve this, the client uses the Offset Retrieving Procedure 214 (Section 5) to obtain the upload's offset. 216 Client Server 217 | | 218 | HEAD with Upload-Token | 219 |----------------------------------------------->| 220 | | 221 | 204 No Content with Upload-Offset | 222 |<-----------------------------------------------| 223 | | 225 Figure 2: Offset Retrieving Procedure 227 3) After the Offset Retrieving Procedure (Section 5) completes, the 228 client can resume the upload by sending the remaining file content to 229 the server, appending to the already stored data in the upload. The 230 Upload-Offset value is included to ensure that the client and server 231 agree on the offset that the upload resumes from. 233 Client Server 234 | | 235 | POST with Upload-Token and Upload-Offset | 236 |----------------------------------------------->| 237 | | 238 | 201 Created on completion | 239 |<-----------------------------------------------| 240 | | 242 Figure 3: Resuming Upload 244 4) If the client is not interesting in completing the upload anymore, 245 it can instruct the server to delete the upload and free all related 246 resources using the Upload Cancellation Procedure (Section 6). 248 Client Server 249 | | 250 | DELETE with Upload-Token | 251 |----------------------------------------------->| 252 | | 253 | 204 No Content on completion | 254 |<-----------------------------------------------| 255 | | 257 Figure 4: Upload Cancellation Procedure 259 3.2. Example 2: Upload as a series of parts 261 In some cases clients might prefer to upload a file as a series of 262 parts sent across multiple HTTP messages. One use case is to 263 overcome server limits on HTTP message content size. Another use 264 case is where the client does not know the final size, such as when 265 file data originates from a streaming source. 267 This example shows how the client, with prior knowledge about the 268 server's resumable upload support, can upload parts of a file over a 269 sequence of procedures. 271 1) If the client is aware that the server supports resumable upload, 272 it can use the Upload Transfer Procedure with the Upload-Incomplete 273 header to start an upload. 275 Client Server 276 | | 277 | POST with Upload-Token, Upload-Offset, | 278 | and Upload-Incomplete | 279 |----------------------------------------------->| 280 | | 281 | 201 Created with Upload-Incomplete | 282 | on completion | 283 |<-----------------------------------------------| 284 | | 286 Figure 5: Upload Transfer Procedure Usage 288 2) The last part of the upload does not have the Upload-Incomplete 289 header. 291 Client Server 292 | | 293 | POST with Upload-Token and Upload-Offset | 294 |----------------------------------------------->| 295 | | 296 | 201 Created on completion | 297 |<-----------------------------------------------| 298 | | 300 Figure 6: Upload Transfer Procedure Last Chunk 302 4. Upload Transfer Procedure 304 The Upload Transfer Procedure is intended for transferring the data 305 chunk. As such, it can be used for either resuming an existing 306 upload, or starting a new upload. A limited form of this procedure 307 MAY be used by the client to start a new upload without the knowledge 308 of server support. 310 This procedure is designed to be compatible with a regular upload. 311 Therefore all methods are allowed with the exception of GET, HEAD, 312 DELETE, and OPTIONS. All response status codes are allowed. The 313 client is RECOMMENDED to use the POST method if not otherwise 314 intended. The server MAY only support a limited number of methods. 316 The client MUST use the same method throughout an entire upload. The 317 server SHOULD reject the attempt to resume an upload with a different 318 method with 400 (Bad Request) response. 320 The request MUST include the Upload-Token header field (Section 7.1) 321 which uniquely identifies an upload. The client MUST NOT reuse the 322 token for a different upload. 324 When resuming an upload, the Upload-Offset header field (Section 7.2) 325 MUST be set to the resumption offset. The resumption offset 0 326 indicates a new upload. The absence of the Upload-Offset header 327 field implies the resumption offset of 0. 329 If the end of the request body is not the end of the upload, the 330 Upload-Incomplete header field (Section 7.3) MUST be set to true. 332 If the server does not consider the upload associated with the token 333 in the Upload-Token header field active, but the resumption offset is 334 non-zero, it MUST respond with 404 (Not Found) status code. 336 The client MUST NOT perform multiple Upload Transfer Procedures 337 (Section 4) for the same token in parallel to avoid race conditions 338 and data loss or corruption. The server is RECOMMENDED to take 339 measures to avoid parallel Upload Transfer Procedures: The server MAY 340 terminate any ongoing Upload Transfer Procedure (Section 4) for the 341 same token. Since the client is not allowed to perform multiple 342 transfers in parallel, the server can assume that the previous 343 attempt has already failed. Therefore, the server MAY abruptly 344 terminate the previous HTTP connection or stream. 346 If the offset in the Upload-Offset header field does not match the 347 value 0, the offset provided by the immediate previous Offset 348 Retrieving Procedure (Section 5), or the end offset of the immediate 349 previous incomplete transfer, the server MUST respond with 409 350 (Conflict) status code. 352 The server MUST send the Upload-Offset header in the response if it 353 considers the upload active, either when the response is a success 354 (e.g. 201 (Created)), or when the response is a failure (e.g. 409 355 (Conflict)). The value MUST be equal to the end offset of the entire 356 upload, or the begin offset of the next chunk if the upload is still 357 incomplete. The client SHOULD consider the upload failed if the 358 response status code indicates a success but the offset in the 359 Upload-Offset header field in the response does not equal to the 360 begin offset plus the number of bytes uploaded in the request. 362 If the request completes successfully and the entire upload is 363 complete, the server MUST acknowledge it by responding with a 364 successful status code between 200 and 299 (inclusive). Server is 365 RECOMMENDED to use 201 (Created) response if not otherwise specified. 366 The response MUST NOT include the Upload-Incomplete header with the 367 value of true. 369 If the request completes successfully but the entire upload is not 370 yet complete indicated by the Upload-Incomplete header, the server 371 MUST acknowledge it by responding with the 201 (Created) status code, 372 the Upload-Incomplete header set to true. 374 :method: POST 375 :scheme: https 376 :authority: example.com 377 :path: /upload 378 upload-token: :SGVs…SGU=: 379 upload-draft-interop-version: 1 380 content-length: 100 381 [content (100 bytes)] 383 :status: 104 384 upload-draft-interop-version: 1 386 :status: 201 387 upload-offset: 100 389 :method: POST 390 :scheme: https 391 :authority: example.com 392 :path: /upload 393 upload-token: :SGVs…SGU=: 394 upload-draft-interop-version: 1 395 upload-offset: 0 396 upload-incomplete: ?1 397 content-length: 25 398 [partial content (25 bytes)] 400 :status: 201 401 upload-incomplete: ?1 402 upload-offset: 25 404 The client MAY automatically attempt upload resumption when the 405 connection is terminated unexpectedly, or if a server error status 406 code between 500 and 599 (inclusive) is received. The client SHOULD 407 NOT automatically retry if a client error status code between 400 and 408 499 (inclusive) is received. 410 File metadata can affect how servers might act on the uploaded file. 411 Clients can send Representation Metadata (see Section 8.3 of [HTTP]) 412 in the Upload Transfer Procedure request that starts an upload. 413 Servers MAY interpret this metadata or MAY ignore it. Clients SHOULD 414 NOT send representation metadata in subsequent Upload Transfer 415 Procedure requests and servers SHOULD ignore representation received 416 in subsequent requests. The Content-Type header can be used to 417 indicate the MIME type of the file. The Content-Disposition header 418 can be used to transmit a filename. If included, the parameters 419 SHOULD be either filename, filename* or boundary. 421 4.1. Feature Detection 423 If the client has no knowledge of whether the server supports 424 resumable upload, the Upload Transfer Procedure MAY be used with some 425 additional constraints. In particular, the Upload-Offset header 426 field (Section 7.2) and the Upload-Incomplete header field 427 (Section 7.3) MUST NOT be sent in the request if the server support 428 is unclear. This allows the upload to function as if it is a regular 429 upload. 431 If the server detects the Upload Transfer Procedure with neither the 432 Upload-Offset header nor the Upload-Incomplete header, and it 433 supports resumable upload, an informational response with 104 (Upload 434 Resumption Supported) status MAY be sent to the client while the 435 request body is being uploaded. 437 The client MUST NOT attempt to resume an upload if it did not receive 438 the 104 (Upload Resumption Supported) informational response, and it 439 does not have other signals of whether the server supporting 440 resumable upload. 442 If the client is aware of the server support, it SHOULD start an 443 upload with the Upload-Offset header set to 0 in order to prevent the 444 unnecessary informational response. 446 4.2. Draft Version Identification 448 *RFC Editor's Note:* Please remove this section and Upload-Draft- 449 Interop-Version from all examples prior to publication of a final 450 version of this document. 452 The current interop version is 1. 454 Client implementations of draft versions of the protocol MUST send a 455 header field Upload-Draft-Interop-Version with the interop version as 456 its value to its requests. Its ABNF is 458 Upload-Draft-Interop-Version = sf-integer 460 Server implementations of draft versions of the protocol MUST NOT 461 send a 104 (Upload Resumption Supported) informational response when 462 the interop version indicated by the Upload-Draft-Interop-Version 463 header field in the request is missing or mismatching. 465 Server implementations of draft versions of the protocol MUST also 466 send a header field Upload-Draft-Interop-Version with the interop 467 version as its value to the 104 (Upload Resumption Supported) 468 informational response. 470 Client implementations of draft versions of the protocol MUST ignore 471 a 104 (Upload Resumption Supported) informational response with 472 missing or mismatching interop version indicated by the Upload-Draft- 473 Interop-Version header field. 475 The reason both the client and the server are sending and checking 476 the draft version is to ensure that implementations of the final RFC 477 will not accidentally interop with draft implementations, as they 478 will not check the existence of the Upload-Draft-Interop-Version 479 header field. 481 5. Offset Retrieving Procedure 483 If an upload is interrupted, the client MAY attempt to fetch the 484 offset of the incomplete upload by sending a HEAD request to the 485 server with the same Upload-Token header field (Section 7.1). The 486 client MUST NOT initiate this procedure without the knowledge of 487 server support. 489 The request MUST use the HEAD method and include the Upload-Token 490 header. The request MUST NOT include the Upload-Offset header or the 491 Upload-Incomplete header. The server MUST reject the request with 492 the Upload-Offset header or the Upload-Incomplete header by sending a 493 400 (Bad Request) response. 495 If the server considers the upload associated with this token active, 496 it MUST send back a 204 (No Content) response. The response MUST 497 include the Upload-Offset header set to the current resumption offset 498 for the client. The response MUST include the Upload-Incomplete 499 header which is set to true if and only if the upload is incomplete. 500 An upload is considered complete if and only if the server completely 501 and successfully received a corresponding Upload Transfer Procedure 502 (Section 4) request with the Upload-Incomplete header being omitted 503 or set to false. 505 The client MUST NOT perform the Offset Retrieving Procedure 506 (Section 5) while the Upload Transfer Procedures (Section 4) is in 507 progress. 509 The offset MUST be accepted by a subsequent Upload Transfer Procedure 510 (Section 4). Due to network delay and reordering, the server might 511 still be receiving data from an ongoing transfer for the same token, 512 which in the client perspective has failed. The server MAY terminate 513 any transfers for the same token before sending the response by 514 abruptly terminating the HTTP connection or stream. Alternatively, 515 the server MAY keep the ongoing transfer alive but ignore further 516 bytes received past the offset. 518 The client MUST NOT start more than one Upload Transfer Procedures 519 (Section 4) based on the resumption offset from a single Offset 520 Retrieving Procedure (Section 5). 522 The response SHOULD include Cache-Control: no-store header to prevent 523 HTTP caching. 525 If the server does not consider the upload associated with this token 526 active, it MUST respond with 404 (Not Found) status code. 528 :method: HEAD 529 :scheme: https 530 :authority: example.com 531 :path: /upload 532 upload-token: :SGVs…SGU=: 533 upload-draft-interop-version: 1 535 :status: 204 536 upload-offset: 100 537 cache-control: no-store 539 The client MAY automatically start uploading from the beginning using 540 Upload Transfer Procedure (Section 4) if 404 (Not Found) status code 541 is received. The client SHOULD NOT automatically retry if a status 542 code other than 204 and 404 is received. 544 6. Upload Cancellation Procedure 546 If the client wants to terminate the transfer without the ability to 547 resume, it MAY send a DELETE request to the server along with the 548 Upload-Token which is an indication that the client is no longer 549 interested in uploading this body and the server can release 550 resources associated with this token. The client MUST NOT initiate 551 this procedure without the knowledge of server support. 553 The request MUST use the DELETE method and include the Upload-Token 554 header. The request MUST NOT include the Upload-Offset header or the 555 Upload-Incomplete header. The server MUST reject the request with 556 the Upload-Offset header or the Upload-Incomplete header by sending a 557 400 (Bad Request) response. 559 If the server has successfully deactivated this token, it MUST send 560 back a 204 (No Content) response. 562 The server MAY terminate any ongoing Upload Transfer Procedure 563 (Section 4) for the same token before sending the response by 564 abruptly terminating the HTTP connection or stream. 566 If the server does not consider the upload associated with this token 567 active, it MUST respond with 404 (Not Found) status code. 569 If the server does not support cancellation, it MUST respond with 405 570 (Method Not Allowed) status code. 572 :method: DELETE 573 :scheme: https 574 :authority: example.com 575 :path: /upload 576 upload-token: :SGVs…SGU=: 577 upload-draft-interop-version: 1 579 :status: 204 581 7. Header Fields 583 7.1. Upload-Token 585 The Upload-Token request header field is an Item Structured Header 586 (see Section 3.3 of [STRUCTURED-FIELDS]) carrying the token used for 587 identification of a specific upload. Its value MUST be a byte 588 sequence. Its ABNF is 590 Upload-Token = sf-binary 592 If not otherwise specified by the server, the client is RECOMMENDED 593 to use 256-bit (32 bytes) cryptographically-secure random binary data 594 as the value of the Upload-Token, in order to ensure that it is 595 globally unique and non-guessable. 597 A conforming implementation MUST be able to handle a Upload-Token 598 field value of at least 128 octets. 600 7.2. Upload-Offset 602 The Upload-Offset request and response header field is an Item 603 Structured Header indicating the resumption offset of corresponding 604 upload, counted in bytes. Its value MUST be an integer. Its ABNF is 606 Upload-Offset = sf-integer 608 7.3. Upload-Incomplete 610 The Upload-Incomplete request and response header field is an Item 611 Structured Header indicating whether the corresponding upload is 612 considered complete. Its value MUST be a boolean. Its ABNF is 614 Upload-Incomplete = sf-boolean 616 8. Redirection 618 The 301 (Moved Permanently) status code and the 302 (Found) status 619 code MUST NOT be used in Offset Retrieving Procedure (Section 5) and 620 Upload Cancellation Procedure (Section 6) responses. A 308 621 (Permanent Redirect) response MAY be persisted for all subsequent 622 procedures. If client receives a 307 (Temporary Redirect) response 623 in the Offset Retrieving Procedure (Section 5), it MAY apply the 624 redirection directly in the immediate subsequent Upload Transfer 625 Procedure (Section 4). 627 9. Security Considerations 629 The tokens inside the Upload-Token header field can be selected by 630 the client which has no knowledge of tokens picked by other client, 631 so uniqueness cannot be guaranteed. If the token is guessable, an 632 attacker can append malicious data to ongoing uploads. To mitigate 633 these issues, 256-bit cryptographically-secure random binary data is 634 recommended for the token. 636 It is OPTIONAL for the server to partition upload tokens based on 637 client identity established through other channels, such as Cookie or 638 TLS client authentication. The client MAY relax the token strength 639 if it is aware of server-side partitioning. 641 10. IANA Considerations 643 This specification registers the following entry in the Permanent 644 Message Header Field Names registry established by [RFC3864]: 646 Header field name: Upload-Token, Upload-Offset, Upload-Incomplete 648 Applicable protocol: http 650 Status: standard 652 Author/change controller: IETF 654 Specification: This document 655 Related information: n/a 657 This specification registers the following entry in the "HTTP Status 658 Codes" registry: 660 Code: 104 662 Description: Upload Resumption Supported 664 Specification: This document 666 11. Normative References 668 [HTTP] Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP 669 Semantics", Work in Progress, Internet-Draft, draft-ietf- 670 httpbis-semantics-19, 12 September 2021, 671 . 674 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 675 Requirement Levels", BCP 14, RFC 2119, 676 DOI 10.17487/RFC2119, March 1997, 677 . 679 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 680 Procedures for Message Header Fields", BCP 90, RFC 3864, 681 DOI 10.17487/RFC3864, September 2004, 682 . 684 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 685 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 686 May 2017, . 688 [STRUCTURED-FIELDS] 689 Nottingham, M. and P-H. Kamp, "Structured Field Values for 690 HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021, 691 . 693 Acknowledgments 695 TODO acknowledge. 697 Appendix 698 Informational Response 700 The server is allowed to respond to Upload Transfer Procedure 701 (Section 4) requests with a 104 (Upload Resumption Supported) 702 intermediate response as soon as the server has validated the 703 request. This way, the client knows that the server supports 704 resumable uploads before the complete response for the Upload 705 Transfer Procedure is received. The benefit is the clients can defer 706 starting the actual data transfer until the server indicates full 707 support of the incoming Upload Transfer Procedure (i.e. resumable are 708 supported, the provided upload token is active etc). 710 On the contrary, support for intermediate responses (the 1XX range) 711 in existing software is limited or not at all present. Such software 712 includes proxies, firewalls, browsers, and HTTP libraries for clients 713 and server. Therefore, the 104 (Upload Resumption Supported) status 714 code is optional and not mandatory for the successful completion of 715 an upload. Otherwise, it might be impossible in some cases to 716 implement resumable upload servers using existing software packages. 717 Furthermore, as parts of the current internet infrastructure 718 currently have limited support for intermediate responses, a 719 successful delivery of a 104 (Upload Resumption Supported) from the 720 server to the client should be assumed. 722 We hope that support for intermediate responses increases in the near 723 future, to allow a wider usage of 104 (Upload Resumption Supported). 725 Feature Detection 727 This specification includes a section about feature detection (it was 728 called service discovery in earlier discussions, but this name is 729 probably ill-suited). The idea is to allow resumable uploads to be 730 transparently implemented by HTTP clients. This means that 731 application developers just keep using the same API of their HTTP 732 library as they have done in the past with traditional, non-resumable 733 uploads. Once the HTTP library gets updated (e.g. because mobile OS 734 or browsers start implementing resumable uploads), the HTTP library 735 can transparently decide to use resumable uploads without explicit 736 configuration by the application developer. Of course, in order to 737 use resumable uploads, the HTTP library needs to know whether the 738 server supports resumable uploads. If no support is detected, the 739 HTTP library should use the traditional, non-resumable upload 740 technique. We call this process feature detection. 742 Ideally, the technique used for feature detection meets following 743 *criteria* (there might not be one approach which fits all 744 requirements, so we have to prioritize them): 746 1. Avoid additional roundtrips by the client, if possible (i.e. an 747 additional HTTP request by the client should be avoided). 749 2. Be backwards compatible to HTTP/1.1 and existing network 750 infrastructure: This means to avoid using new features in HTTP/2, 751 or features which might require changes to existing network 752 infrastructure (e.g. nginx or HTTP libraries) 754 3. Conserve the user's privacy (i.e. the feature detection should 755 not leak information to other third-parties about which URLs have 756 been connected to) 758 Following *approaches* have already been considered in the past. All 759 except the last approaches have not been deemed acceptable and are 760 therefore not included in the specification. This follow list is a 761 reference for the advantages and disadvantages of some approaches: 763 *Include a support statement in the SETTINGS frame.* The SETTINGS 764 frame is a HTTP/2 feature and is sent by the server to the client to 765 exchange information about the current connection. The idea was to 766 include an additional statement in this frame, so the client can 767 detect support for resumable uploads without an additional roundtrip. 768 The problem is that this is not compatible with HTTP/1.1. 769 Furthermore, the SETTINGS frame is intended for information about the 770 current connection (not bound to a request/response) and might not be 771 persisted when transmitted through a proxy. 773 *Include a support statement in the DNS record.* The client can 774 detect support when resolving a domain name. Of course, DNS is not 775 semantically the correct layer. Also, DNS might not be involved if 776 the record is cached or retrieved from a hosts files. 778 *Send a HTTP request to ask for support.* This is the easiest 779 approach where the client sends an OPTIONS request and uses the 780 response to determine if the server indicates support for resumable 781 uploads. An alternative is that the client sends the request to a 782 well-known URL to obtain this response, e.g. /.well-known/resumable- 783 uploads. Of course, while being fully backwards-compatible, it 784 requires an additional roundtrip. 786 *Include a support statement in previous responses.* In many cases, 787 the file upload is not the first time that the client connects to the 788 server. Often additional requests are sent beforehand for 789 authentication, data retrieval etc. The responses for those requests 790 can also include a header which indicates support for resumable 791 uploads. There are two options: - Use the standardized Alt-Svc 792 response header. However, it has been indicated to us that this 793 header might be reworked in the future and could also be semantically 794 different from our intended usage. - Use a new response header 795 Resumable-Uploads: https://example.org/files/* to indicate under 796 which endpoints support for resumable uploads is available. 798 *Send a 104 intermediate response to indicate support.* The clients 799 normally starts a traditional upload and includes a header indicate 800 that it supports resumable uploads (e.g. Upload-Offset: 0). If the 801 server also supports resumable uploads, it will immediately respond 802 with a 104 intermediate response to indicate its support, before 803 further processing the request. This way the client is informed 804 during the upload whether it can resume from possible connection 805 errors or not. While an additional roundtrip is avoided, the problem 806 with that solution is that many HTTP server libraries do not support 807 sending custom 1XX responses and that some proxies may not be able to 808 handle new 1XX status codes correctly. 810 *Send a 103 Early Hint response to indicate support.* This approach 811 is the similar to the above one, with one exception: Instead of a new 812 104 (Upload Resumption Supported) status code, the existing 103 813 (Early Hint) status code is used in the intermediate response. The 814 103 code would then be accompanied by a header indicating support for 815 resumable uploads (e.g. Resumable-Uploads: 1). It is unclear 816 whether the Early Hints code is appropriate for that, as it is 817 currently only used to indicate resources for prefetching them. 819 Upload Metadata 821 The Upload Transfer Procedure (Section 4) allows the Content-Type and 822 Content-Disposition header to be included. They are intended to be a 823 standardized way of communicating the file name and file type, if 824 available. However, this is not without controversy. Some argue 825 that since these headers are already defined in other specifications, 826 it is not necessary to include them here again. Furthermore, the 827 Content-Disposition header field's format is not clearly enough 828 defined. For example, it is left open which disposition value should 829 be used in the header. There needs to be more discussion whether 830 this approach is suited or not. 832 However, from experience with the tus project, users are often asking 833 for a way to communicate the file name and file type. Therefore, we 834 believe it is help to explicitly include an approach for doing so. 836 FAQ 838 * *Are multipart requests supported?* Yes, requests whose body is 839 encoded using the multipart/form-data are implicitly supported. 840 The entire encoded body can be considered as a single file, which 841 is then uploaded using the resumable protocol. The server, of 842 course, must store the delimiter ("boundary") separating each part 843 and must be able to parse the multipart format once the upload is 844 completed. 846 Authors' Addresses 848 Marius Kleidl 849 Transloadit Ltd 850 Email: marius@transloadit.com 852 Jiten Mehta 853 Apple Inc. 854 Email: jmehta@apple.com 856 Guoye Zhang 857 Apple Inc. 858 Email: guoye_zhang@apple.com 860 Lucas Pardue 861 Cloudflare 862 Email: lucaspardue.24.7@gmail.com 864 Stefan Matsson 865 JellyHive 866 Email: s.matsson@gmail.com