idnits 2.17.1 draft-wright-http-partial-upload-01.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: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (December 05, 2019) is 1604 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7233 (Obsoleted by RFC 9110) Summary: 3 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTP A. Wright 3 Internet-Draft December 05, 2019 4 Intended status: Experimental 5 Expires: June 7, 2020 7 Partial Uploads in HTTP 8 draft-wright-http-partial-upload-01 10 Abstract 12 This document specifies a new media type intended for use in PATCH 13 payloads that allows a resource to be uploaded in several segments, 14 instead of a single large request. 16 Status of This Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at https://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on June 7, 2020. 33 Copyright Notice 35 Copyright (c) 2019 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (https://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 51 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 2 52 2. Modifying a content range with PATCH . . . . . . . . . . . . 3 53 3. Segmented upload with PATCH . . . . . . . . . . . . . . . . . 3 54 3.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 4 55 4. Registrations . . . . . . . . . . . . . . . . . . . . . . . . 5 56 4.1. 2__ (Sparse Resource) status code . . . . . . . . . . . . 5 57 4.2. message/byterange media type . . . . . . . . . . . . . . 6 58 5. Security Considerations . . . . . . . . . . . . . . . . . . . 6 59 5.1. Unallocated ranges . . . . . . . . . . . . . . . . . . . 6 60 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 6 61 6.1. Normative References . . . . . . . . . . . . . . . . . . 6 62 6.2. Informative References . . . . . . . . . . . . . . . . . 7 63 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 7 65 1. Introduction 67 This introduces a mechanism that allows user agents to upload a 68 document over several requests. Similar solutions have been known as 69 partial uploads, segmented uploading, or resumable uploads. 71 HTTP is a stateless protocol, which implies that if a request is 72 interrupted, there can be no way to resume it. This is not normally 73 an issue if there is an alternate way of arriving to the desired 74 state from an incomplete state transition. For example, if a 75 download is interrupted, the user-agent may request just the missing 76 parts in a Range request. However, if an upload is interrupted, no 77 method exists for the client to synchronize its state with the server 78 and only upload the remaining data; the entire request must be 79 canceled and retried. This document standardizes a media type for 80 PATCH and a new status code for uploading new resources over several 81 segmented requests. 83 1.1. Notational Conventions 85 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 86 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 87 "OPTIONAL" in this document are to be interpreted as described in BCP 88 14 [RFC2119] [RFC8174] when, and only when, they appear in all 89 capitals, as shown here. 91 This document uses ABNF as defined in [RFC5234] and imports grammar 92 rules from [RFC7230]. 94 For brevity, example HTTP requests or responses may add newlines or 95 whitespace, or omit some headers necessary for message transfer. 97 2. Modifying a content range with PATCH 99 The PATCH method [RFC5789] allows a client to modify a resource in a 100 specific way, as specified by the request payload. This document 101 formalizes the concept of using "multipart/byteranges" [RFC7233] as a 102 patch file, allowing usage in PATCH; and introduces a simplified form 103 "message/byterange" that only patches a single range. 105 The "message/byterange" form may be used in a request as so: 107 PATCH /uploads/foo HTTP/1.1 108 Content-Type: message/byterange 109 Content-Length: 283 110 If-Match: "xyzzy" 111 If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT 113 Content-Range: bytes 100-299/600 114 Content-Type: text/plain 115 Content-Length: 200 117 [200 bytes...] 119 This request asks to modify a 600-byte document, overwriting 200 120 bytes of it, starting at a 100-byte offset. 122 3. Segmented upload with PATCH 124 As an alternative to using PUT to create a new resource, the contents 125 of a resource may be uploaded in segments, each written across 126 several PATCH requests. 128 The first PATCH request creates the resource and uploads the first 129 segment. To ensure the resource does not exist, the request SHOULD 130 include "If-None-Match: *". The request payload is a "message/ 131 byterange" document containing the first segment of the resource to 132 be uploaded, and the total length of the resource to be uploaded. 133 Upon processing, the server returns "2__ Sparse Resource" indicating 134 the document is error-free up to this point, but that more writes are 135 necessary before the resource will be considered fully written. 137 Additional segments are uploaded with the same format. 139 When the final segment is uploaded, the server detects the resource 140 is completely uploaded, and returns the final status code. 142 If the client loses the state of the upload, or the connection is 143 terminated, the user agent can re-synchronize by issuing a "HEAD" 144 request for the resource to get the current uploaded length. The 145 response will typically be 200 (OK) or 2__ (Sparse Resource). If 146 2__, the user agent may resume uploading the document from that 147 offset. 149 3.1. Example 151 A single PUT request that creates a new file can be split apart into 152 multiple PATCH requests. Here is an example that uploads a 600-byte 153 document across three 200-byte segments. 155 The first PATCH request creates the resource: 157 PATCH /uploads/foo HTTP/1.1 158 Content-Type: message/byterange 159 Content-Length: 281 160 If-None-Match: * 162 Content-Range: bytes 0-199/600 163 Content-Type: text/plain 164 Content-Length: 200 166 [200 bytes...] 168 This request allocates a 600 byte document, and uploading the first 169 200 bytes of it. The server responds with 2__ (Sparse Resource), 170 indicating that the resource has been allocated and all uploaded data 171 is saved, but acknowledging the more data must still be uploaded by 172 the client. 174 Additional requests upload the remainder of the document: 176 PATCH /uploads/foo HTTP/1.1 177 Content-Type: message/byterange 178 Content-Length: 283 179 If-None-Match: * 181 Content-Range: bytes 200-399/600 182 Content-Type: text/plain 183 Content-Length: 200 185 [200 bytes...] 187 This second request also returns 2__ (Sparse Resource), since there 188 are still 200 bytes that are not written to. 190 A third request uploads the final portion of the document: 192 PATCH /uploads/foo HTTP/1.1 193 Content-Type: message/byterange 194 Content-Length: 283 195 If-None-Match: * 197 Content-Range: bytes 200-399/600 198 Content-Type: text/plain 199 Content-Length: 200 201 [200 bytes...] 203 Since the document is fully written to, the server responds with 200 204 (OK), the same response as if the entire 600 bytes were written in a 205 PUT request. 207 4. Registrations 209 4.1. 2__ (Sparse Resource) status code 211 The 2__ (Sparse Resource) status code indicates that while the 212 request succeeded, the request target is not ready for use, and the 213 server is awaiting more data to be written. 215 In response to a GET request, representations returned with this 216 status code might not be valid according to their media type, but 217 could become valid once more data is appended. 219 In response to a PATCH request, it means the operation succeeded, but 220 more uploads are necessary before the server can do anything else 221 with the resource. 223 This is a 2xx class status because it indicates the request was 224 filled as requested, and may safely be handled the same as a 200 (OK) 225 response. However, it is only expected to be seen by clients making 226 partial uploads; clients not expecting this status MAY treat it as an 227 error. 229 Responses to a HEAD request MUST return the same end-to-end headers 230 as a GET request. Normally, HTTP allows HEAD responses to omit 231 certain header fields related to the payload; however Content-Length 232 and Content-Range are essential fields for synchronizing the state of 233 partial uploads. Hop-by-hop headers may still be omitted. 235 Several alternate names for this status code can be considered, 236 including: Incomplete Content, Partial Resource, or Incomplete 237 Upload. 239 4.2. message/byterange media type 241 The "message/byterange" media type patches the defined byte range to 242 some specified contents. It is similar to the "multipart/byteranges" 243 media type, except it omits the multipart separator, and so only 244 allows a single range to be specified. 246 It follows the syntax of HTTP message headers and body. It MUST 247 include the Content-Range header field. If the message length is 248 known by the sender, it SHOULD contain the Content-Length header 249 field. Unknown or nonapplicable header fields MUST be ignored. 251 "header-field" and "message-body" are specified in [RFC7230]. 253 byterange-document = *( header-field CRLF ) 254 CRLF 255 [ message-body ] 257 A patch is applied to a document by changing the range of bytes to 258 the contents of the patch message payload. Servers MAY treat an 259 invalid or nonexistent range as an error. 261 5. Security Considerations 263 5.1. Unallocated ranges 265 Servers must consider what happens when clients make writes to a 266 sparse file. 268 Servers will normally only allow patch ranges to start inside or 269 immediately after the end of the representation. Servers supporting 270 sparse writes MUST NOT disclose the contents of memory. This may be 271 done at file creation time, or left to the filesystem if it can 272 guarantee this behavior. 274 6. References 276 6.1. Normative References 278 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 279 Requirement Levels", BCP 14, RFC 2119, 280 DOI 10.17487/RFC2119, March 1997, 281 . 283 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 284 Specifications: ABNF", STD 68, RFC 5234, 285 DOI 10.17487/RFC5234, January 2008, 286 . 288 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 289 Protocol (HTTP/1.1): Message Syntax and Routing", 290 RFC 7230, DOI 10.17487/RFC7230, June 2014, 291 . 293 [RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., 294 "Hypertext Transfer Protocol (HTTP/1.1): Range Requests", 295 RFC 7233, DOI 10.17487/RFC7233, June 2014, 296 . 298 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 299 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 300 May 2017, . 302 6.2. Informative References 304 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 305 RFC 5789, DOI 10.17487/RFC5789, March 2010, 306 . 308 Author's Address 310 Austin Wright 312 Email: aaa@bzfx.net