Resumable Uploads for HTTP

3.1. Example 1: Complete Upload of Representation Data with Known Size

In this example, the client first attempts to upload representation data with a known size in a single HTTP request to the resource at /project/123/files. An interruption occurs and the client then attempts to resume the upload using subsequent HTTP requests to the upload resource at /uploads/abc.¶

1) The client notifies the server that it wants to begin an upload (Section 6). The server reserves the required resources to accept the upload from the client and then sends an interim response to the client, signaling support for resumable uploads and the upload resource's URI via the Location header field (Section 10.2.2 of [HTTP]). The client can start sending the representation data in the request content immediately after the request header section. Alternatively, it can wait for the interim response first.¶

2) If the connection to the server is interrupted, the client might want to resume the upload. However, before this is possible, the client needs to know the amount of representation data that the server processed before the interruption. It does so by retrieving the offset (Section 7) from the upload resource.¶

3) The client can resume the upload by sending the remaining representation data to the upload resource (Section 8), appending to the already stored representation data in the upload using the application/partial-upload media type. The Upload-Offset header field is included to ensure that the client and server agree on the offset that the upload resumes from. Once the remaining representation data is transferred, the server processes the entire representation and responds with whatever the initial request to /project/123/files would have produced if it had not been interrupted, e.g., a 200 (OK) response.¶

4) If the client is not interested in completing the upload, it can cancel the upload (Section 9). The server can then release the upload resource and any associated representation data.¶

3.2. Example 2: Upload as a Series of Parts

In some cases, clients might prefer to upload a representation as a series of parts sent serially across multiple HTTP messages. One use case is to overcome server limits on HTTP message content size. Another use case is where the client does not know the final size of the representation data, such as when the data originates from a streaming source.¶

This example shows how the client, communicating with a resource known to support resumable uploads, can upload parts of a representation incrementally.¶

1) The client is aware that the target resource supports resumable uploads and therefore starts the upload with the Upload-Complete header field set to false and the first part of the representation.¶

2) Next, intermediate parts are appended (Section 8) with the Upload-Complete header field set to false, indicating that they are not the last part of the representation data.¶

3) If the connection was interrupted, the client might want to resume the upload, similar to the previous example (Section 3.1). The client retrieves the offset (Section 7) to learn the amount of representation data processed by the server and then continues appending the remaining parts to the upload as in the previous step.¶

4) The request to append the last part of the representation data has the Upload-Complete header field set to true to indicate the complete transfer. Once the remaining representation data is transferred, the server processes the entire representation and responds with whatever the initial request to /project/123/files would have produced if its representation had been fully transferred and processed, e.g., a 200 (OK) response.¶

4.1. Offset

The offset is the number of bytes from the representation data that have been processed, either during the creation of the upload resource (Section 6) or by appending to it (Section 8). The offset is required when appending representation data (Section 8) to synchronize the client and resource regarding the amount of transferred representation data.¶

The offset reflects application-level processing for the upload. Data might have been delivered and acknowledged at the transport layer without yet being reflected in the offset.¶

Representation data processed by the upload resource cannot be removed again and, therefore, the offset as seen by the client MUST NOT decrease. Clients can use this guarantee to free resources associated with transferred representation data, as no retransmission of it will be necessary. If the server loses any part of the state, it MUST deactivate the upload resource and reject further interaction with it.¶

4.2. Completeness

An upload is incomplete until it is explicitly marked as complete by the client or the server. After this point, no more representation data can be appended.¶

4.3. Length

The length of the representation data might not be known when starting the transfer, for example, because the representation is taken from a streaming source. The representation's length will, however, be known at the latest when the client completes the upload (Section 4.2).¶

A client SHOULD communicate the representation's length to the server as soon as it becomes known, without waiting for the upload to complete. This aids resource management and allows early validation. A request that creates the upload resource (Section 6) or appends to it (Section 8) has two possible indicators of the length:¶

1. If the request includes the Upload-Complete header field set to true, the request content is the remaining representation data. The representation's length is then the sum of the current offset (Section 4.1) and the request content's length, which might be announced in the Content-Length header field.¶

2. The request can include the Upload-Length header field defined below.¶

If indicators (1) and (2) are both present in the same request, their indicated lengths MUST match. The representation's length, if known, MUST stay consistent across subsequent requests. A server can use the problem type [PROBLEM] of "https://iana.org/assignments/http-problem-types#inconsistent-upload-length" (Section 14.2) in responses to indicate inconsistent length indicators.¶

Note that the length and offset values do not determine whether an upload is complete. Instead, the client uses the Upload-Complete header field (Section 4.2.1) to indicate that a request completes the upload. The offset could match the length, but the upload can still be incomplete.¶

5.1. Upload-Limit

The Upload-Limit response header field is a Dictionary Structured Header Field ([STRUCTURED-FIELDS]). Its value is a Dictionary (Section 3.2 of [STRUCTURED-FIELDS]). Other values MUST cause the entire header field to be ignored.¶

Receivers of the Upload-Limit header field parse the Dictionary as described in Section 4.2 of [STRUCTURED-FIELDS]. Where the Dictionary is successfully parsed, this document places two additional requirements on Dictionary members. First, a member with an unknown key MUST be ignored. Second, a member with a known key but a value of unexpected type MUST cause the entire Upload-Limit header field to be ignored, or alternatively the complete HTTP message MUST be treated as malformed.¶

The following key-value pairs are defined.¶

5.2. Use with OPTIONS

A client can use an OPTIONS request without the Upload-Complete header field to discover whether the resource supports resumable uploads and to learn potential limits before creating an upload resource.¶

When responding to such a request, if the target resource supports the creation of a resumable upload resource (Section 6), the server MUST include the Upload-Limit header field with the corresponding limits in the response. If a server is configured such that all of its resources support the creation of upload resources with identical limits, it SHOULD include the Upload-Limit header field in response to an OPTIONS request for the target * (if this target is supported).¶

In an OPTIONS response, the presence of the Upload-Limit header field signals support for resumable uploads, even when the server applies no limits. An empty Dictionary is equivalent to omitting the field (Section 3.2 of [STRUCTURED-FIELDS]), so it cannot carry this signal. If the server does not apply any limits, it MUST send min-size=0.¶

To reduce the likelihood of failing requests, the limits announced in an OPTIONS response SHOULD NOT be less restrictive than the limits applied to an upload once the upload resource has been created, unless the request to create an upload resource included additional information that warrants different limits. For example, a server might announce a general maximum size limit of 1 GB, but reduce it to 100 MB when the media type indicates an image.¶

5.3. Limit Changes

Throughout the lifetime of the upload resource, limits SHOULD NOT change in a way that causes failures for clients adhering to the initially discovered limits. If the client discovers that it cannot continue the upload while adhering to the limits, it SHOULD stop the current request immediately (Section 19) and cancel the upload (Section 9).¶

The following recommendations for limit changes can minimize the risk of causing upload failures:¶

• max-size and max-append-size SHOULD NOT decrease.¶

• min-size and min-append-size SHOULD NOT increase.¶

• Between subsequent responses, the end of the upload resource's lifetime as implied by max-age SHOULD NOT decrease.¶

5.4. Limit Violations

When a request is rejected because limits were violated, the response SHOULD include the Upload-Limit header field carrying all limits of the corresponding upload if possible. This might not be possible if intermediaries enforce limits.¶

Servers, including intermediaries, can (and often do) apply restrictions on the size of individual request message content. There is no standard mechanism to communicate such existing size restriction. A server that implements one can respond with a 413 (Content Too Large) status code; see Section 15.5.14 of [HTTP]. Appending to an upload resource, as a series of appends, can be used to upload data up to the max-size limit (Section 5.1.1) without encountering per-message limits. Servers might apply restrictions that are smaller than the append limits, which would also result in a failed request.¶

When a client receives a response with a 413 (Content Too Large) status code during upload creation (Section 6) or append (Section 8), it SHOULD retry the request with a smaller size residing between min-append-size (Section 5.1.4) and max-append-size (Section 5.1.3). If these limits are unknown at the time of receiving such a response, the client can attempt to discover them through an OPTIONS request (Section 5.2). Retrying with the same request content size will likely yield the same error response. Cases where the request content size matches the min-append-size limit yet fails with a 413 (Content Too Large) response might indicate a deployment mismatch that cannot be recovered from.¶

6.1. Client Behavior

A client can start a resumable upload from any request that can carry content by including the Upload-Complete header field (Section 4.2.1). Any method that allows content can be used, such as POST, PUT, and PATCH. The request can benefit from incremental delivery; see Section 18.¶

The Upload-Complete header field is set to true if the request content includes the entire representation data that the client intends to upload. This is also a requirement for transparently upgrading to resumable uploads from conventional uploads (Section 17.1.1).¶

If the client knows the representation's length, it SHOULD indicate the length in the request to help the server allocate necessary resources for the upload and provide early feedback if the representation violates a limit (Section 5), as described in Section 4.3.¶

Clients are not required to discover limits (Section 5) before starting the upload and might therefore be initially unaware of limits enforced by the server. However, the client SHOULD respect any limits (Section 5) announced during the upload process in the Upload-Limit header field in interim or final responses. In particular, if the allowed maximum size is less than the amount of representation data the client intends to upload, the client SHOULD stop the current request immediately (Section 19) and cancel the upload (Section 9). If the client knows that the representation data is smaller than min-size (Section 5.1.2), it cannot expect resumability to be offered. The client might still attempt to transfer the representation in a single request, either in a request with the Upload-Complete header field set to true (see Section 17.1.1) or via a conventional upload.¶

The request content can be empty. If the Upload-Complete header field is then set to true, the client intends to upload an empty representation. An Upload-Complete header field set to false is also valid. This can be used to retrieve the upload resource's URI before transferring any representation data. Since interim responses are optional, this technique provides another mechanism to learn the URI, at the cost of an additional round trip before data upload can commence.¶

Representation metadata included in the initial request (see Section 8.2 of [HTTP]) can affect how servers act on the uploaded representation data. The Content-Type header field (Section 8.3 of [HTTP]) indicates the media type of the representation. The Content-Encoding header field (Section 8.4 of [HTTP]) names the content codings applied to the representation. The Content-Disposition header field ([CONTENT-DISPOSITION]) can be used to transmit a filename. For this purpose, the inline disposition type is RECOMMENDED.¶

If the client receives a final response with the Upload-Complete: ?1 header field, the upload is complete and the corresponding response comes from the target resource of the initial request (Section 4.2.1). Note that this does not necessarily indicate success. 4xx (Client Error) or 5xx (Server Error) status codes indicate in this case an error occurred while processing the representation, and therefore, resuming the upload would not resolve this error.¶

If the client receives a 2xx (Successful) final response with the Upload-Complete header field set to false or missing, and the client's Upload-Complete request header field was set to false, the Location response header field points the client to the created upload resource. The client can continue appending representation data to it (Section 8).¶

If the client receives a 4xx (Client Error) or 5xx (Server Error) final response with the Upload-Complete header field set to false or missing, or if it did not receive a final response, it can apply the heuristics described in Section 11 to retry or resume the upload.¶

6.2. Server Behavior

Upon receiving a request with the Upload-Complete header field, the server can choose to offer resumption support for this request by creating an upload resource. If so, the server SHOULD announce the upload resource by sending an interim response with the 104 (Upload Resumption Supported) status code unless the server is not capable of sending interim responses. The interim response allows the client to resume the upload even if the message exchange gets later interrupted. When sent, it MUST include Location header field pointing to the upload resource and MUST include the Upload-Limit header field with the corresponding limits (Section 5) if any.¶

The target resource of the initial request is responsible for processing the representation data transferred in the resumable upload according to the method and header fields in the initial request. The upload resource, on the other hand, enables resuming the transfer.¶

If the Upload-Complete request header field is set to true, the client intends to transfer the entire representation data in one request. If the request content was fully processed, no resumable upload is needed and the server proceeds to process the request and generate a response. The server MUST NOT generate a 2xx (Successful) response with the Upload-Complete header field set to false or missing in response to a request with the Upload-Complete request header field set to true.¶

If the Upload-Complete request header field is set to false, the client intends to transfer the representation over multiple requests. If the request content was fully processed, the server MUST include the Location response header field pointing to the upload resource and MUST include the Upload-Limit header field with the corresponding limits if any. Servers are RECOMMENDED to use the 201 (Created) status code.¶

The server MUST record the representation's length according to Section 4.3 if the Upload-Length or Upload-Complete: ?1 header fields are included in the request.¶

While the request content is being processed, the server MAY send multiple interim responses with a 104 (Upload Resumption Supported) status code and the Upload-Offset header field set to the current offset to inform the client about the upload progress.¶

Every response to the same request that identifies the upload resource in the Location header field MUST use the same URI. A final response with Upload-Complete: ?1 is the result of processing the representation, so its Location header field can identify a different resource. Clients SHOULD check that the upload resource URI does not change, and SHOULD stop the current request immediately (Section 19) and cancel the upload (Section 9) if it does.¶

The server SHOULD include the Upload-Complete header field (Section 4.2.1) in the response to indicate whether it is the result of processing the uploaded representation.¶

The server SHOULD NOT generate a response with the 301 (Moved Permanently), 302 (Found), or 303 (See Other) status codes and the Upload-Complete: ?0 header field because clients might follow the redirect without preserving the original method. See Section 20.7 for redirecting a response that completes the upload.¶

The server might not process the entire request content when the upload is interrupted, for example, because of a dropped connection or a canceled request. In this case, the server SHOULD append as much of the request content as possible to the upload resource, allowing the client to resume the upload from where it was interrupted. The upload resource MUST NOT be considered complete in this case.¶

6.3. Examples

A) The following example shows an upload creation, where all 123456789 bytes are transferred in the initial request. The server sends multiple interim responses and one final response from processing the uploaded representation.¶

POST /project/123/files HTTP/1.1
Host: example.com
Content-Disposition: inline; filename="file name.jpg"; filename*=UTF-8''file%20name.jpg
Content-Length: 123456789
Upload-Length: 123456789
Upload-Complete: ?1

[content (123456789 bytes)]

HTTP/1.1 104 Upload Resumption Supported
Location: https://example.com/upload/b530ce8ff
Upload-Limit: max-size=1234567890

HTTP/1.1 104 Upload Resumption Supported
Upload-Offset: 23456789

HTTP/1.1 200 OK
Upload-Complete: ?1
Content-Type: application/json

{"attachmentId": "b530ce8ff"}

B) The following example shows an upload creation, where only the first 23456789 bytes of a 123456789-byte upload are transferred. The server acknowledges the processed representation data and that the upload is not complete yet. The client can continue appending data.¶

POST /upload HTTP/1.1
Host: example.com
Upload-Complete: ?0
Content-Length: 23456789
Upload-Length: 123456789

[partial content (23456789 bytes)]

HTTP/1.1 104 Upload Resumption Supported
Location: https://example.com/upload/3fd4994ad
Upload-Limit: max-size=1234567890

HTTP/1.1 201 Created
Location: https://example.com/upload/3fd4994ad
Upload-Complete: ?0
Upload-Limit: max-size=1234567890

C) The following example shows an upload creation, where the server responds with a 5xx (Server Error) status code. Thanks to the interim response containing the upload resource URI, the client can resume the upload.¶

POST /upload HTTP/1.1
Host: example.com
Upload-Complete: ?1
Content-Length: 123456789
Upload-Length: 123456789

[content (123456789 bytes)]

HTTP/1.1 104 Upload Resumption Supported
Location: https://example.com/upload/0587fa44b

HTTP/1.1 500 Internal Server Error

D) The following example shows an upload creation being rejected by the server because the request content cannot be decoded. The Upload-Complete header field in the response is set to true because, after the decoding failure, the server does not want the rest of the representation and considers the upload complete. The client cannot continue the upload.¶

POST /upload-gzip HTTP/1.1
Host: example.com
Upload-Complete: ?0
Content-Length: 23456789
Upload-Length: 123456789
Content-Encoding: gzip

[corrupted gzip content]

HTTP/1.1 104 Upload Resumption Supported
Location: https://example.com/upload/6723cdf37

HTTP/1.1 400 Bad Request
Upload-Complete: ?1

7.1. Client Behavior

If the client wants to resume the upload after an interruption, it has to know the amount of representation data processed by the upload resource so far. It can fetch the offset by sending a HEAD or GET request to the upload resource. Using HEAD is RECOMMENDED, since response content is not required for resumption. Upon a successful response, the client can continue the upload by appending representation data (Section 8) starting at the offset indicated by the Upload-Offset response header field.¶

The offset can be less than or equal to the number of bytes of representation data that the client has already sent. The client is expected to handle backtracking of a reasonable length. On the other hand, the offset can be greater than the amount of sent representation data, for example, if the server already has data from an earlier attempt to upload the same representation. If the client is not able to provide the representation data at the given offset, the upload MUST be considered a failure. The client then MUST NOT continue the upload and SHOULD cancel the upload (Section 9).¶

The client MUST NOT retrieve the offset while it is still creating (Section 6) or appending to (Section 8) the same upload resource, because the server might terminate the in-progress request (Section 10).¶

If the client receives a 2xx (Successful) response with a valid Upload-Offset header field, the client can continue appending representation data to it (Section 8).¶

If the client receives a 2xx (Successful) response without a valid Upload-Offset header field, a 4xx (Client Error) or 5xx (Server Error) response, or if it did not receive a response, the client MAY retry retrieving the offset.¶

7.2. Server Behavior

A successful response to a HEAD or GET request to an upload resource¶

• MUST include the offset in the Upload-Offset header field (Section 4.1.1),¶

• MUST indicate the limits in the Upload-Limit header field (Section 5) if any, and¶

• SHOULD include the Cache-Control header field with the value no-store to prevent HTTP caching ([HTTP-CACHING]).¶

The server SHOULD NOT generate a response with the 301 (Moved Permanently), 302 (Found), or 303 (See Other) status codes because clients might follow the redirect without preserving the HEAD method.¶

A client does not require response content for an offset retrieval request in order to successfully resume an upload. Therefore, serving response content for a GET request is unexpected. Its meaning is not defined by this protocol.¶

7.3. Examples

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.¶

HEAD /upload/c35e2cd29 HTTP/1.1
Host: example.com

HTTP/1.1 204 No Content
Upload-Complete: ?0
Upload-Offset: 25000000
Upload-Length: 100000000
Upload-Limit: max-age=3600
Cache-Control: no-store

8.1. Client Behavior

A client can continue the upload and append representation data by sending a PATCH request with the application/partial-upload media type (Section 13) to the upload resource. The request content is the representation data to append. The request can benefit from incremental delivery; see Section 18.¶

The client MUST indicate the offset of the request content inside the representation data by including the Upload-Offset header field. To ensure that the upload resource accepts the request, the client SHOULD take the offset from the most recent offset retrieval (Section 7), upload creation (Section 6), or upload append (Section 8) response.¶

The request MUST include the Upload-Complete header field. Its value is true in two cases:¶

• the request has content that is the end of the representation data. Once the content is fully processed by the server, the upload is complete.¶

• the request has no content. Once the request is processed by the server, the upload is complete. This usage requires the full representation data to have been processed during prior requests.¶

If the client receives a final response with the Upload-Complete: ?1 header field, the upload is complete and the corresponding response comes from the target resource of the initial request (Section 4.2.1). Note that this does not necessarily indicate success. 4xx (Client Error) or 5xx (Server Error) status codes indicate in this case an error occurred while processing the representation, and therefore, resuming the upload would not resolve this error.¶

If the client receives a 4xx (Client Error) or 5xx (Server Error) final response with the Upload-Complete header field set to false or missing, or if it did not receive a final response, it can apply the heuristics described in Section 11 to retry or resume the upload. Otherwise, the upload is considered a failure.¶

8.2. Server Behavior

A server applies a PATCH request with the application/partial-upload media type (Section 13) to an upload resource by appending the patch document in the request content.¶

The server might not process the entire patch document when the upload is interrupted, for example, because of a dropped connection or a canceled request. In this case, the server SHOULD append as much of the patch document as possible to the upload resource, starting at its beginning and without discontinuities. Appending a continuous section starting at the patch document's beginning constitutes a successful PATCH as defined in Section 2 of [PATCH]. Saving the processed data allows the client to resume the upload from where it was interrupted. The upload resource MUST NOT be considered complete in this case.¶

If the Upload-Offset request header field value does not match the current offset (Section 4.1), the server MUST reject the request with a 409 (Conflict) status code and the Upload-Complete header field set to false. 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" (Section 14.1).¶

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 target resource of the initial upload creation request (Section 6) would have generated if it had processed the entire representation in the initial request. However, the response MUST include the Upload-Complete header field set to true, 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. The server MUST NOT generate a 2xx (Successful) response with the Upload-Complete header field set to false or missing in response to a request with the Upload-Complete request header field set to true.¶

If the Upload-Complete request header field is set to false, the client intends to transfer the remaining representation data over multiple requests. If the request content was fully processed, the server acknowledges the appended data by sending a 2xx (Successful) response with the Upload-Complete header field set to false.¶

Even if the upload is complete (Section 4.2) from the server's perspective and the final response from the target resource of the initial request has already been sent, the client might still perform an upload append (Section 8) after an offset retrieval (Section 7) 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.¶

The server MUST record the representation's length according to Section 4.3 if the Upload-Length or Upload-Complete: ?1 header fields are included in the request. If the representation's length is known, the server MUST NOT let the offset exceed it: if appending a request's content would take the offset past the length, the server MUST reject the request, deactivate the upload resource, and reject any further interaction with it. It is not sufficient to rely on the Content-Length header field for enforcement because this header field might not be present.¶

While the request content is being processed, the server SHOULD send interim responses with a 104 (Upload Resumption Supported) status code and the Upload-Offset header field set to the current offset to inform the client about the upload progress. These interim responses MUST NOT include the Location header field.¶

The server SHOULD include the Upload-Complete header field (Section 4.2.1) in the response to indicate whether it is the result of processing the uploaded representation.¶

The server SHOULD NOT generate a response with the 301 (Moved Permanently), 302 (Found), or 303 (See Other) status codes and the Upload-Complete: ?0 header field because clients might follow the redirect without preserving the PATCH method. See Section 20.7 for redirecting a response that completes the upload.¶

8.3. Examples

A) The following example shows an upload append request. The client transfers the next 3456789 bytes at an offset of 20000000 and does not indicate that the upload is then completed. The server generates one interim response, when the offset reached 21728394 bytes, and finally acknowledges the new offset:¶

PATCH /upload/37a504d87 HTTP/1.1
Host: example.com
Upload-Complete: ?0
Upload-Offset: 20000000
Content-Length: 3456789
Content-Type: application/partial-upload

[content (3456789 bytes)]

HTTP/1.1 104 Upload Resumption Supported
Upload-Offset: 21728394

HTTP/1.1 204 No Content
Upload-Complete: ?0

B) The following example shows an upload append, where the client transfers the remaining 4567890 bytes and completes the upload with a length of 1234567890 bytes. The server processes the uploaded representation and generates the corresponding response, in this example containing extracted metadata:¶

PATCH /upload/d38d6ffe8 HTTP/1.1
Host: example.com
Upload-Complete: ?1
Upload-Offset: 1230000000
Content-Length: 4567890
Content-Type: application/partial-upload

[content (4567890 bytes)]

HTTP/1.1 200 OK
Upload-Complete: ?1
Content-Type: application/json

{
  "metadata": {
    [...]
  }
}

9.1. Client Behavior

If the client wants to cancel the upload, it can send a DELETE request to the upload resource. Doing so is an indication that the client is no longer interested in continuing the upload, and that the server can release any resources associated with it.¶

9.2. Server Behavior

Upon receiving a DELETE request, the server SHOULD deactivate the upload resource.¶

The server SHOULD terminate any in-flight requests to the upload resource before sending the response by abruptly terminating their HTTP connection(s) or stream(s), as described in Section 10.¶

The server SHOULD NOT generate a response with the 301 (Moved Permanently), 302 (Found), or 303 (See Other) status codes because clients might follow the redirect without preserving the DELETE method.¶

9.3. Example

The following example shows an upload cancellation:¶

DELETE /upload/5688a431c HTTP/1.1
Host: example.com

HTTP/1.1 204 No Content

14.1. Mismatching Offset

This section defines the "https://iana.org/assignments/http-problem-types#mismatching-upload-offset" problem type [PROBLEM]. A server can use this problem type when responding to an upload append request (Section 8) to indicate that the Upload-Offset header field in the request does not match the upload resource's offset.¶

Two problem type extension members are defined: the expected-offset and provided-offset members. A response using this problem type SHOULD populate both members, with the value of expected-offset taken from the upload resource and the value of provided-offset taken from the upload append request.¶

The following example shows a response, where the resource's offset was 12500000, but the client attempted to append at offset 25000000:¶

# NOTE: '\' line wrapping per RFC 8792

HTTP/1.1 409 Conflict
Content-Type: application/problem+json
Upload-Offset: 12500000
Upload-Complete: ?0

{
  "type":"https://iana.org/assignments/http-problem-types#\
    mismatching-upload-offset",
  "title": "offset from request does not match offset of resource",
  "expected-offset": 12500000,
  "provided-offset": 25000000
}

14.2. 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 (Section 6) or upload append request (Section 8) to indicate that the request includes inconsistent length values, as described in Section 4.3.¶

The following example shows a response:¶

# NOTE: '\' line wrapping per RFC 8792

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Upload-Complete: ?0

{
  "type":"https://iana.org/assignments/http-problem-types#\
    inconsistent-upload-length",
  "title": "inconsistent length values for upload"
}

17.1. Optimistic Upload Creation

An "optimistic upload creation" can be used regardless of the client's knowledge about the resource's support for resumable uploads. However, the client needs to be able to process interim responses. An upload creation request then includes the full representation data because the client anticipates that it will be transferred without interruptions or resumed if an interruption occurs.¶

The benefit of this strategy is that if the upload creation request succeeds, the representation data is transferred in a single request without additional round trips.¶

A possible drawback is that the client might be unable to resume an upload. If an upload is interrupted before the client receives a 104 (Upload Resumption Supported) interim response with the upload resource's URI, the client cannot resume that upload due to the missing URI. The interim response might not be received if the interruption happens too early in the message exchange, the target resource of the initial request does not support resumable uploads, the server is not capable of sending the 104 interim response, or an intermediary dropped the interim response. Without a 104 interim response, the client needs to either treat the upload as failed or retry the entire upload creation request if this is allowed by the application.¶

A client might wait for a limited duration to receive a 104 interim response before starting to transmit the request content. This way, the client can learn about the resource's support for resumable uploads and/or the upload resource's URI. This is conceptually similar to how a client might wait for a 100 (Continue) interim response (see Section 10.1.1 of [HTTP]) before committing to work.¶

17.2. Careful Upload Creation

For a "careful upload creation" the client knows that the target resource of the initial request supports resumable uploads and sends an empty upload creation request without including any representation data. Upon successful response reception, the client can use the included upload resource URI to transmit the representation data (Section 8) and resume the upload at any stage if an interruption occurs. The response can include the Upload-Limit header field, which indicates limits for the rest of the upload (Section 5).¶

The retransmission of representation data or the ultimate upload failure that can happen with an "optimistic upload creation" is therefore avoided at the expense of an additional request that does not carry representation data.¶

This approach is best suited if the client cannot receive interim responses, e.g., due to a limitation in the provided HTTP interface, or if large representations are transferred where the cost of the additional request is minuscule compared to the effort of transferring the representation itself.¶

20.1. Upload Resource URIs

The upload resource URI is the identifier used for modifying the upload. Without further protection of this URI, an attacker can perform any operation on the upload resource: obtain information about it, append data to it, or cancel it. Each of these requests can also cause a server to terminate an in-flight request from a legitimate client (Section 10).¶

To mitigate these risks, the server SHOULD ensure that only authorized clients can access the upload resource. It is also RECOMMENDED that upload resource URIs be hard to guess.¶

Servers might embed information in the upload resource URI, such as a storage or processing location, to make request routing more efficient. Because the URI is visible to the client and to anyone else who obtains it, servers MUST NOT include information in it that is not intended to be exposed. Routing information could, for instance, be encoded so that only the server can interpret it.¶

If knowing the upload resource URI is enough to access the upload, the URI is in effect a credential. Like other credentials, it needs to be protected in transit (see Section 17.16.1 of [HTTP]). URIs are also often logged or displayed by servers, proxies, and user agents, so the URI can be disclosed to third parties (see Section 17.9 of [HTTP]).¶

20.2. Untrusted Input

Uploaded representation data and its metadata are untrusted input. Server operators have to be careful about where uploaded data is written and subsequently accessed, especially if the operations cause the representation to be processed or executed by the server. In addition, metadata MUST be validated and/or sanitized if the server takes its values into consideration for processing or storing the representation.¶

20.3. Content Scanning

Some servers or intermediaries provide scanning of content uploaded by clients. Any scanning mechanism that relies on receiving a complete representation in a single request message can be defeated by resumable uploads because content can be split across multiple messages. Servers or intermediaries wishing to perform content scanning SHOULD consider how resumable uploads can circumvent scanning and take appropriate measures. Possible strategies include waiting for the upload to complete before scanning the entire representation, or disabling resumable uploads.¶

20.4. Time-of-Check to Time-of-Use

There can be a significant delay between the creation of an upload resource and its completion. Policy decisions or authorization checks performed on the initial request might become outdated or invalid by the time the upload completes. To mitigate vulnerabilities arising from time-of-check to time-of-use (TOCTOU) conditions, the server SHOULD validate that the user is still allowed to perform the requested action before finalizing the upload. This includes, for example, validating access privileges and quota policies associated with the upload resource.¶

20.5. Resource Exhaustion

Resumable uploads are vulnerable to Slowloris-style attacks [SLOWLORIS]. A malicious client can create upload resources and keep them alive by regularly sending PATCH requests with no or small content to the upload resources. This could be abused to exhaust server resources by creating and holding open uploads indefinitely with minimal work. Servers SHOULD provide mitigations for Slowloris attacks, such as increasing the maximum number of clients the server will allow, limiting the number of uploads a single client is allowed to make, imposing restrictions on the minimum transfer speed an upload is allowed to have, and restricting the length of time an upload resource can exist.¶

20.6. Message Size Limits

Uploads performed as a series of appends can be used to upload data up to the max-size limit (Section 5.1.1), which could be a larger size than a server or intermediary might normally permit in conventional single upload request message content. Servers or intermediaries need to consider that relying solely on message content limits to constrain resources allocated to uploads might not be an effective strategy when using resumable uploads.¶

20.7. Different Origins

The target resource of the initial request (Section 6) and the upload resource might have different origins ([ORIGIN]). For example, the initial request might be sent to an application server, while the upload resource is hosted by a dedicated storage service.¶

Clients have to consider this change of origin when following the Location header field to the upload resource. Credentials and other per-origin state associated with the target resource of the initial request are not necessarily applicable to the upload resource, and remain scoped to their respective origins. Clients also have to consider that disclosing an upload resource URI to a different origin can leak the capability to read, append to, or cancel the upload.¶

Because the upload can be completed either by the initial request or by an upload append request (Section 8), the final response might come from a different origin depending on whether the upload was resumed. To avoid this, the server MAY respond to the request that completes the upload with a 303 (See Other) status code, redirecting the user agent to the origin of the target resource of the initial request. Because a 303 (See Other) response directs the user agent to retrieve the result with GET, the considerations regarding method preservation in Section 6 and Section 8 do not apply in this case.¶

21.1. HTTP Fields

IANA is asked to register the following entries in the "Hypertext Transfer Protocol (HTTP) Field Name Registry":¶

21.2. HTTP Status Code

IANA is asked to register the following entry in the "Hypertext Transfer Protocol (HTTP) Status Code Registry":¶

Value:

104 (suggested value)¶

Description:

Upload Resumption Supported¶

Specification:

Section 12 of RFC nnnn¶

21.3. Media Type

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 Section 20 of RFC nnnn¶

Interoperability considerations:

N/A¶

Published specification:

Section 13 of RFC nnnn¶

Applications that use this media type:

Applications that transfer files over unreliable networks or want pausable 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¶

21.4. HTTP Problem Types

IANA is asked to register the following entry in the "HTTP Problem Types" registry:¶

Type URI:

https://iana.org/assignments/http-problem-types#mismatching-upload-offset¶

Title:

Mismatching Upload Offset¶

Recommended HTTP status code:

409¶

Reference:

Section 14.1 of RFC nnnn¶

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¶

Title:

Inconsistent Upload Length Values¶

Recommended HTTP status code:

400¶

Reference:

Section 14.2 of RFC nnnn¶

22.1. Normative References

[CONTENT-DISPOSITION]

Reschke, J., "Use of the Content-Disposition Header Field in the Hypertext Transfer Protocol (HTTP)", RFC 6266, DOI 10.17487/RFC6266, June 2011, <https://www.rfc-editor.org/rfc/rfc6266>.

[HTTP]

Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Semantics", STD 97, RFC 9110, DOI 10.17487/RFC9110, June 2022, <https://www.rfc-editor.org/rfc/rfc9110>.

[HTTP-CACHING]

Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Caching", STD 98, RFC 9111, DOI 10.17487/RFC9111, June 2022, <https://www.rfc-editor.org/rfc/rfc9111>.

[HTTP/1.1]

Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP/1.1", STD 99, RFC 9112, DOI 10.17487/RFC9112, June 2022, <https://www.rfc-editor.org/rfc/rfc9112>.

[HTTP/2]

Thomson, M., Ed. and C. Benfield, Ed., "HTTP/2", RFC 9113, DOI 10.17487/RFC9113, June 2022, <https://www.rfc-editor.org/rfc/rfc9113>.

[HTTP/3]

Bishop, M., Ed., "HTTP/3", RFC 9114, DOI 10.17487/RFC9114, June 2022, <https://www.rfc-editor.org/rfc/rfc9114>.

[PATCH]

Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC 5789, DOI 10.17487/RFC5789, March 2010, <https://www.rfc-editor.org/rfc/rfc5789>.

[PROBLEM]

Nottingham, M., Wilde, E., and S. Dalal, "Problem Details for HTTP APIs", RFC 9457, DOI 10.17487/RFC9457, July 2023, <https://www.rfc-editor.org/rfc/rfc9457>.

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/rfc/rfc2119>.

[RFC8174]

Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

[STRUCTURED-FIELDS]

Nottingham, M. and P. Kamp, "Structured Field Values for HTTP", RFC 9651, DOI 10.17487/RFC9651, September 2024, <https://www.rfc-editor.org/rfc/rfc9651>.

22.2. Informative References

[INCREMENTAL]

Oku, K., Pauly, T., and M. Thomson, "Incremental Forwarding of HTTP Messages", RFC 10036, DOI 10.17487/RFC10036, August 2026, <https://www.rfc-editor.org/rfc/rfc10036>.

[ORIGIN]

Barth, A., "The Web Origin Concept", RFC 6454, DOI 10.17487/RFC6454, December 2011, <https://www.rfc-editor.org/rfc/rfc6454>.

[RFC8792]

Watsen, K., Auerswald, E., Farrel, A., and Q. Wu, "Handling Long Lines in Content of Internet-Drafts and RFCs", RFC 8792, DOI 10.17487/RFC8792, June 2020, <https://www.rfc-editor.org/rfc/rfc8792>.

[SLOWLORIS]

"RSnake" Hansen, R., "Welcome to Slowloris - the low bandwidth, yet greedy and poisonous HTTP client!", June 2009, <https://web.archive.org/web/20150315054838/http://ha.ckers.org/slowloris/>.

Since draft-ietf-httpbis-resumable-upload-13

Editorial changes only.¶

Since draft-ietf-httpbis-resumable-upload-12

• Upload-Complete and Upload-Length are no longer required on offset retrieval responses.¶

• Remove discouragement against sending requests after expiration.¶

• Clarify how upload offset is inferred from responses.¶

• Disallow successful responses indicating an incomplete upload when the request indicated completion.¶

• Describe considerations for the initially targeted resource and the upload resource having different origins.¶

Since draft-ietf-httpbis-resumable-upload-11

• Clear up different responsibilities of server and upload resource.¶

• Relax recommendations on client handling greater offsets.¶

• Clarify client behavior for 413 responses.¶

• Remove Accept-Patch from OPTIONS responses.¶

• Allow upload creation requests with no content regardless of the min-append-size limit.¶

• Remove nominative languages addressing the lost final response.¶

• Allow max-age limit to decrease as expected.¶

• Redefine Upload-Complete on the server side.¶

• Recommend incremental delivery.¶

• Clarify min-size limit and its client behavior.¶

• Describe GET requests against upload resource.¶

• Replace uses of term "upload length" with "representation's length".¶

• Include Upload-Limit in response to limit violation.¶

• Clarify that clients might not know limits when starting upload.¶

• Remove section covering integrity digests.¶

• Increase the draft interop version.¶

• Add version-specific details on cancelling in-flight transfers.¶

• Clarify client retry strategies.¶

Since draft-ietf-httpbis-resumable-upload-10

• Add recommended disposition type for file name indication.¶

Since draft-ietf-httpbis-resumable-upload-09

• Requires Accept-Patch in OPTIONS.¶

• Add security consideration regarding time-of-check to time-of-use.¶

• Lift requirement on Upload-Complete for all final responses.¶

• Relax requirements on limit changes.¶

• Describe the interaction between 100 and 104 responses.¶

• Numerous editorial improvements.¶

Since draft-ietf-httpbis-resumable-upload-08

• Clarify definitions of new header fields.¶

• Make handling of OPTIONS * optional.¶

• Require server to announce limits using Upload-Limit.¶

• Require clients to adhere to known limits.¶

• Rephrase requirements for concurrency handling, focusing on the outcome.¶

• Remove requirement for 204 status code for DELETE responses.¶

• Increase the draft interop version.¶

• Add section about 104 status code.¶

• Rephrase recommendation for sending information back to client.¶

Since draft-ietf-httpbis-resumable-upload-07

• Clarify server handling when upload length is exceeded.¶

• Extend security considerations about upload resource URIs, representation metadata, and untrusted inputs.¶

• Allow clients to retry for appropriate 4xx responses.¶

Since draft-ietf-httpbis-resumable-upload-06

• Minor editorial improvements to introduction and examples.¶

• Define structured types for new header fields.¶

Since draft-ietf-httpbis-resumable-upload-05

• Increase the draft interop version.¶

• Numerous editorial changes.¶

• Rename expires limit to max-age.¶

• Require Upload-Complete, but not Upload-Offset or Upload-Limit, for append responses.¶

• Add problem type for inconsistent length values.¶

• Reduce use of "file" in favor of "representation".¶

Since draft-ietf-httpbis-resumable-upload-04

• Clarify implications of Upload-Limit header.¶

• Allow client to fetch upload limits upfront via OPTIONS.¶

• Add guidance on upload creation strategy.¶

• Add Upload-Length header to indicate length during creation.¶

• Describe possible usage of Want-Repr-Digest.¶

Since draft-ietf-httpbis-resumable-upload-03

• Add note about Content-Location for referring to subsequent resources.¶

• Require application/partial-upload for appending to uploads.¶

• Explain handling of content and transfer codings.¶

• Add problem types for mismatching offsets and completed uploads.¶

• Clarify that completed uploads must not be appended to.¶

• Describe interaction with Digest Fields from RFC9530.¶

• Require that upload offset does not decrease over time.¶

• Add Upload-Limit header field.¶

• Increase the draft interop version.¶

Since draft-ietf-httpbis-resumable-upload-02

• Add upload progress notifications via informational responses.¶

• Add security consideration regarding request filtering.¶

• Explain the use of empty requests for creation uploads and appending.¶

• Extend security consideration to include resource exhaustion attacks.¶

• Allow 200 status codes for offset retrieval.¶

• Increase the draft interop version.¶

Since draft-ietf-httpbis-resumable-upload-01

• Replace Upload-Incomplete header with Upload-Complete.¶

• Replace terminology about procedures with HTTP resources.¶

• Increase the draft interop version.¶

Since draft-ietf-httpbis-resumable-upload-00

• Remove Upload-Token and instead use Server-generated upload URL for upload identification.¶

• Require the Upload-Incomplete header field in Upload Creation Procedure.¶

• Increase the draft interop version.¶

Since draft-tus-httpbis-resumable-uploads-protocol-02

None¶

Since draft-tus-httpbis-resumable-uploads-protocol-01

• Clarifying backtracking and preventing skipping ahead during the Offset Receiving Procedure.¶

• Clients auto-retry 404 is no longer allowed.¶

Since draft-tus-httpbis-resumable-uploads-protocol-00

• Split the Upload Transfer Procedure into the Upload Creation Procedure and the Upload Appending Procedure.¶