diff --git a/draft-ietf-httpbis-resumable-upload.md b/draft-ietf-httpbis-resumable-upload.md index 4a868fcfb..e98d44acf 100644 --- a/draft-ietf-httpbis-resumable-upload.md +++ b/draft-ietf-httpbis-resumable-upload.md @@ -293,8 +293,6 @@ A resumable upload is enabled through interaction with an upload resource. When An upload resource is specific to the upload of one representation. For uploading multiple representations, multiple upload resources have to be used. -The server can clean up an upload resource and make it inaccessible immediately after the upload is complete. However, if a client didn't receive the last response acknowledging the upload's completion and the upload resource is not available anymore, the client cannot verify the upload's state with the server. Therefore, the server SHOULD keep the upload resource available for a reasonable amount of time after the upload is complete, or provide an alternate, application-specific way for the client to verify the completion of the upload. - An upload resource SHOULD be unique. Reuse of a URI for a different upload resource SHOULD be avoided in order to reduce the chance of misdirected or corrupted upload resources, as well as the potential security issues described in {{security-considerations}}. ## State @@ -532,7 +530,7 @@ The resource SHOULD NOT generate a response with the `301 (Moved Permanently)` a ### Examples {#offset-retrieving-example} -A) The following example shows an offset retrieval request. The server indicates the current offset and that the upload is not complete yet. The client can continue to append representation data. +The following example shows an offset retrieval request. The server indicates the current offset and that the upload is not complete yet. The client can continue to append representation data. ~~~ http-message HEAD /upload/c35e2cd29 HTTP/1.1 @@ -548,21 +546,6 @@ Upload-Limit: max-age=3600 Cache-Control: no-store ~~~ -B) The following example shows an offset retrieval request for a completed upload. The client does not need to continue the upload. - -~~~ http-message -HEAD /upload/a9edb781b HTTP/1.1 -Host: example.com -~~~ - -~~~ http-message -HTTP/1.1 204 No Content -Upload-Complete: ?1 -Upload-Offset: 100000000 -Upload-Length: 100000000 -Cache-Control: no-store -~~~ - ## Upload Append {#upload-appending} ### Client Behavior @@ -595,12 +578,7 @@ The server might not process the entire patch document when the upload is interr If the `Upload-Offset` request header field value does not match the current offset ({{upload-offset}}), the server MUST reject the request with a `409 (Conflict)` status code. The response MUST include the correct offset in the `Upload-Offset` header field. The response can use the problem type {{PROBLEM}} of "https://iana.org/assignments/http-problem-types#mismatching-upload-offset" ({{mismatching-offset}}). -If the upload is already complete ({{upload-complete}}), the server MUST NOT modify the upload resource and MUST reject the request. The choice of response depends on the nature of the upload request and server state, including but not limited to: - -- If the client attempted to append a non-zero length document, the server MUST treat this as an inconsistent length failure. The server can use the problem type {{PROBLEM}} of "https://iana.org/assignments/http-problem-types#inconsistent-upload-length" ({{inconsistent-length}}) in the response. -- If the client attempted to append a zero-length document: - - If the server retains knowledge of the upload resource but it is not available, the `410 (Gone)` status code can be used; the response could also contain a `Location` header field to indicate the location of the completed upload. The server can use the problem type {{PROBLEM}} of "https://iana.org/assignments/http-problem-types#completed-upload" ({{completed-upload}}) in the response. - - If the server has not retained knowledge of the upload resource, a `404 (Not Found)` status code can be used. +Even if the upload is complete ({{upload-complete}}) in the server's perspective and the final response from the targeted resource has already been sent, the client might still perform an upload append {#upload-appending} after an offset retrieval {#offset-retrieving} due to the response being lost during transmission. The server can choose to replay the final response to the client if the request to append to the completed upload is valid. If the `Upload-Complete` request header field is set to true, the client intends to transfer the remaining representation data in one request. If the request content was fully processed, the upload is marked as complete and the server SHOULD generate the response that matches what the resource, that was targeted by the initial upload creation ({{upload-creation}}), would have generated if it had processed the entire representation in the initial request. However, the response MUST include the `Upload-Complete` header field with a true value, allowing clients to identify whether a response, in particular error responses, is related to the resumable upload itself or the processing of the uploaded representation. @@ -733,25 +711,6 @@ Content-Type: application/problem+json } ~~~ -## Completed Upload - -This section defines the "https://iana.org/assignments/http-problem-types#completed-upload" problem type {{PROBLEM}}. A server can use this problem type when responding to an upload append request ({{upload-appending}}) to indicate that the upload has already been completed and cannot be modified. - -The following example shows an example response: - -~~~ http-message -# NOTE: '\' line wrapping per RFC 8792 - -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" -} -~~~ - ## Inconsistent Length This section defines the "https://iana.org/assignments/http-problem-types#inconsistent-upload-length" problem type {{PROBLEM}}. A server can use this problem type when responding to an upload creation ({{upload-creation}}) or upload append request ({{upload-appending}}) to indicate that the request includes inconsistent upload length values, as described in {{upload-length}}. @@ -802,14 +761,6 @@ Content digests help verify the integrity of the content in an individual reques If the client knows the integrity digest of the content from an upload creation ({{upload-creation}}) or upload appending ({{upload-appending}}) request, it can include the `Content-Digest` header field in the request. Once the request is complete, the server can compute the integrity digest of the content and compare it to the provided digest. If the digests don't match the server SHOULD consider the transfer failed, not append the content to the upload resource, and signal the failure to the client. This way, the integrity of an individual request can be protected. -# Responses to Uploads - -HTTP uploads often not only transfer a representation to the server but also send back information to the client. For resumable uploads, this works similarly to conventional HTTP uploads. The server can include information in the response to the request that transferred the remaining representation data and included the `Upload-Complete: ?1` header field. Clients can regard this response as the final response for the entire upload, as detailed in {{upload-creation}} and {{upload-appending}}. - -However, due to network interruptions, the server might process the remaining representation data, complete the upload, and send a response to the client, which then does not receive the response. The client can learn that the upload is complete by retrieving its state ({{offset-retrieving}}), but resumable uploads as defined in this document do not offer functionality to recover the missed response. - -To address this issue, the server can send the desired information in header fields, which are included in both the final response and responses when the client fetches the upload state via a HEAD request ({{offset-retrieving}}). This way, the client can retrieve the information from the header even if it failed to receive the final response. If the piece of information is too large for header fields, the server could make it available as a separate resource for retrieval and point the client to its URI in an appropriate header field. - # Upload Strategies The definition of the upload creation request ({{upload-creation}}) provides the client with flexibility to choose whether the representation data is fully or partially transferred in the first request, or if no representation data is included at all. Which behavior is best largely depends on the client's capabilities, its desire to avoid data re-transmission, and its knowledge about the resource's support for resumable uploads. @@ -963,20 +914,6 @@ Reference: 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: -: {{completed-upload}} of 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#inconsistent-upload-length