From a226475a23216912d8654e787c8b7526d3b2c6a3 Mon Sep 17 00:00:00 2001 From: Marius Kleidl Date: Fri, 1 Mar 2024 16:46:24 +0100 Subject: [PATCH 1/5] Add `application/partial-upload` media type --- draft-ietf-httpbis-resumable-upload.md | 68 +++++++++++++++++++++++++- 1 file changed, 67 insertions(+), 1 deletion(-) diff --git a/draft-ietf-httpbis-resumable-upload.md b/draft-ietf-httpbis-resumable-upload.md index 62cfa3613..0c9869fa0 100644 --- a/draft-ietf-httpbis-resumable-upload.md +++ b/draft-ietf-httpbis-resumable-upload.md @@ -324,7 +324,7 @@ The client SHOULD NOT automatically retry if a client error status code between Upload appending is used for resuming an existing upload. -The request MUST use the `PATCH` method and be sent to the upload resource. The `Upload-Offset` field value ({{upload-offset}}) MUST be set to the resumption offset. +The request MUST use the `PATCH` method and `application/partial-upload` media type and be sent to the upload resource. The `Upload-Offset` field value ({{upload-offset}}) MUST be set to the resumption offset. If the end of the request content is not the end of the upload, the `Upload-Complete` field value ({{upload-complete}}) MUST be set to false. @@ -336,6 +336,8 @@ The client MUST NOT perform multiple upload transfers for the same upload resour If the offset indicated by the `Upload-Offset` field value does not match the offset provided by the immediate previous offset retrieval ({{offset-retrieving}}), or the end offset of the immediate previous incomplete successful transfer, the server MUST respond with a `409 (Conflict)` status code. +The server applies the patch document of the `application/partial-upload` media type by appending the unmodified request content to the targeted upload resource. + While the request content is being uploaded, the target resource MAY send one or more informational responses with a `104 (Upload Resumption Supported)` status code to the client. These informational responses MUST NOT contain the `Location` header field. They MAY include the `Upload-Offset` header field with the current upload offset as the value to inform the client about the upload progress. The same restrictions on the `Upload-Offset` header field in informational responses from the upload creation ({{upload-creation}}) apply. The server MUST send the `Upload-Offset` header field in the response 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. `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 still incomplete. The client SHOULD consider the upload failed if the status code indicates a success but the offset indicated by the `Upload-Offset` field value does not equal the total of begin offset plus the number of bytes uploaded in the request. @@ -354,6 +356,7 @@ Host: example.com Upload-Offset: 100 Upload-Draft-Interop-Version: 4 Content-Length: 100 +Content-Type: application/partial-upload [content (100 bytes)] ~~~ @@ -406,6 +409,10 @@ The `Upload-Complete` request and response header field indicates whether the co The `Upload-Complete` header field MUST only be used if support by the resource is known to the client ({{feature-detection}}). +# 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 size on the block of data and it might be empty. The start and end of block of data might align with the start and end of the file that should be uploaded, but are not required to do so. + # Redirection The `301 (Moved Permanently)` and `302 (Found)` status codes MUST NOT be used in offset retrieval ({{offset-retrieving}}) and upload cancellation ({{upload-cancellation}}) responses. For other responses, the upload resource MAY return a `308 (Permanent Redirect)` status code and clients SHOULD use new permanent URI for subsequent requests. If the client receives a `307 (Temporary Redirect)` response to an offset retrieval ({{offset-retrieving}}) request, it MAY apply the redirection directly in an immediate subsequent upload append ({{upload-appending}}). @@ -438,6 +445,65 @@ Description: Specification: : This document +IANA is asked to register the following entry in the "Media Types" registry: + +Type name: +: application + +Subtype name: +: partial-upload + +Required parameters: +: N/A + +Optional parameters: +: N/A + +Encoding considerations: +: binary + +Security considerations: +: see {{security-considerations}} 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 + --- back # Informational Response From 589fd7b32c79e617ef9d0a273bb31aba24b3e4d2 Mon Sep 17 00:00:00 2001 From: Marius Kleidl Date: Wed, 12 Jun 2024 11:45:12 +0200 Subject: [PATCH 2/5] Feedback from @smatsson --- draft-ietf-httpbis-resumable-upload.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/draft-ietf-httpbis-resumable-upload.md b/draft-ietf-httpbis-resumable-upload.md index 4ce1eaf76..39924a794 100644 --- a/draft-ietf-httpbis-resumable-upload.md +++ b/draft-ietf-httpbis-resumable-upload.md @@ -335,7 +335,7 @@ The client SHOULD NOT automatically retry if a 4xx (Client Error) status code is Upload appending is used for resuming an existing upload. -The request MUST use the `PATCH` method and `application/partial-upload` media type and be sent to the upload resource. The `Upload-Offset` field value ({{upload-offset}}) MUST be set to the resumption offset. +The request MUST use the `PATCH` method with the `application/partial-upload` media type and MUST be sent to the upload resource. The `Upload-Offset` field value ({{upload-offset}}) MUST be set to the resumption offset. If the end of the request content is not the end of the upload, the `Upload-Complete` field value ({{upload-complete}}) MUST be set to false. @@ -347,7 +347,7 @@ The client MUST NOT perform multiple upload transfers for the same upload resour If the offset indicated by the `Upload-Offset` field value does not match the offset provided by the immediate previous offset retrieval ({{offset-retrieving}}), or the end offset of the immediate previous incomplete successful transfer, the server MUST respond with a `409 (Conflict)` status code. -The server applies the patch document of the `application/partial-upload` media type by appending the unmodified request content to the targeted upload resource. +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 as was received. While the request content is being uploaded, the target resource MAY send one or more informational responses with a `104 (Upload Resumption Supported)` status code to the client. These informational responses MUST NOT contain the `Location` header field. They MAY include the `Upload-Offset` header field with the current upload offset as the value to inform the client about the upload progress. The same restrictions on the `Upload-Offset` header field in informational responses from the upload creation ({{upload-creation}}) apply. @@ -424,7 +424,7 @@ The `Upload-Complete` header field MUST only be used if support by the resource # 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 size on the block of data and it might be empty. The start and end of block of data might align with the start and end of the file that should be uploaded, but are not required to do so. +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. # Redirection From 4dccfeda6dcc6df2754cae46e21415a807951a87 Mon Sep 17 00:00:00 2001 From: Marius Kleidl Date: Mon, 24 Jun 2024 21:47:59 +0200 Subject: [PATCH 3/5] Update changelog --- draft-ietf-httpbis-resumable-upload.md | 1 + 1 file changed, 1 insertion(+) diff --git a/draft-ietf-httpbis-resumable-upload.md b/draft-ietf-httpbis-resumable-upload.md index 6eb12a38b..3c3065b8e 100644 --- a/draft-ietf-httpbis-resumable-upload.md +++ b/draft-ietf-httpbis-resumable-upload.md @@ -588,6 +588,7 @@ The authors would like to thank Mark Nottingham for substantive contributions to {:numbered="false"} * Add note about `Content-Location` for referring to subsequent resources. +* Require `application/partial-upload` for appending to uploads. ## Since draft-ietf-httpbis-resumable-upload-02 {:numbered="false"} From dcd15ddd8f8be66e358ab8ea123fd901868b8b4b Mon Sep 17 00:00:00 2001 From: Marius Kleidl Date: Mon, 24 Jun 2024 22:11:25 +0200 Subject: [PATCH 4/5] Explicit mention that as much data should be saved as possible --- draft-ietf-httpbis-resumable-upload.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/draft-ietf-httpbis-resumable-upload.md b/draft-ietf-httpbis-resumable-upload.md index 3c3065b8e..8b6473204 100644 --- a/draft-ietf-httpbis-resumable-upload.md +++ b/draft-ietf-httpbis-resumable-upload.md @@ -219,6 +219,8 @@ If the request includes an `Upload-Complete` field value set to true and a valid The request content MAY be empty. If the `Upload-Complete` header field is then set to true, the client intends to upload an empty resource representation. An `Upload-Complete` header field is set to false is also valid. This can be used to create an upload resource URL before transferring data, which can save client or server resources. Since informational responses are optional, this technique provides another mechanism to learn the URL, at the cost of an additional round-trip before data upload can commence. +If the server does not receive the entire request content, for example because of canceled requests or dropped connections, it SHOULD append as much of the request content starting at its beginning and without discontinuities as possible. If the server did not append the entire request content, the upload MUST NOT be considered complete. + The following example shows an upload creation. The client transfers the entire 100 bytes in the first request. The server generates two informational responses to transmit the upload resource's URL and progress information, and one final response to acknowledge the completed upload: ~~~ http-message @@ -347,7 +349,7 @@ The client MUST NOT perform multiple upload transfers for the same upload resour If the offset indicated by the `Upload-Offset` field value does not match the offset provided by the immediate previous offset retrieval ({{offset-retrieving}}), or the end offset of the immediate previous incomplete successful transfer, the server MUST respond with a `409 (Conflict)` status code. -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 as was received. +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 send one or more informational responses with a `104 (Upload Resumption Supported)` status code to the client. These informational responses MUST NOT contain the `Location` header field. They MAY include the `Upload-Offset` header field with the current upload offset as the value to inform the client about the upload progress. The same restrictions on the `Upload-Offset` header field in informational responses from the upload creation ({{upload-creation}}) apply. From e67b4029b836ec41a4f82cb8a851333dbb1ac89f Mon Sep 17 00:00:00 2001 From: Marius Kleidl Date: Mon, 24 Jun 2024 22:21:36 +0200 Subject: [PATCH 5/5] Add reference --- draft-ietf-httpbis-resumable-upload.md | 1 + 1 file changed, 1 insertion(+) diff --git a/draft-ietf-httpbis-resumable-upload.md b/draft-ietf-httpbis-resumable-upload.md index 8b6473204..2d9f38f8f 100644 --- a/draft-ietf-httpbis-resumable-upload.md +++ b/draft-ietf-httpbis-resumable-upload.md @@ -45,6 +45,7 @@ author: normative: HTTP: RFC9110 + RFC5789: informative: