Skip to content

RESUMABLE: Remove nominative languages addressing the lost final response #3405

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
guoye-zhang wants to merge 1 commit into
base: main
Choose a base branch
from
+2 −65
Open

RESUMABLE: Remove nominative languages addressing the lost final response #3405

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 2 additions & 65 deletions draft-ietf-httpbis-resumable-upload.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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}}.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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

Expand Down
Loading