]> Transloadit

ietf@mariuskleidl.net

Apple Inc.

guoye_zhang@apple.com

Apple

lucas@lucaspardue.com

Web and Internet Transport HTTP HTTP, upload, resumable HTTP data transfers can encounter interruption due to reasons such as canceled requests or dropped connections. If the intended recipient can indicate how much of the data was processed prior to interruption, a sender can resume data transfer at that point instead of attempting to transfer all of the data again. HTTP range requests support this concept of resumable downloads from server to client. This document describes a mechanism that supports resumable uploads from client to server using HTTP. About This Document Status information for this document may be found at . Discussion of this document takes place on the HTTP Working Group mailing list (), which is archived at . Working Group information can be found at . Source for this draft and an issue tracker can be found at .

Introduction HTTP data transfers can encounter interruption due to reasons such as canceled requests or dropped connections. If the intended recipient can indicate how much of the data was processed prior to interruption, a sender can resume data transfer at that point instead of attempting to transfer all of the data again. HTTP range requests (see ) support this concept of resumable data transfers for downloads from server to client. While partial PUT is one method for uploading a partial representation (via the Content-Range header field in the request), there are caveats that affect its deployability; see . Upload requests can be canceled for various reasons, including but not limited to:

explicit client cancellation:

e.g., terminating a user-agent process

implicit client cancellation:

e.g., terminating a tab, garbage collecting a process, or an internal error

explicit server cancellation:

e.g., scheduled maintenance

implicit server cancellation:

e.g., denial-of-service mitigation or an internal error

Connections can be dropped due to a variety of network or transport layer reasons triggered by endpoints or on-path elements. This specification defines a new mechanism for resumable uploads from client to server that can seamlessly fall back to conventional uploads. When an upload is interrupted, clients can send subsequent requests to query the server state and use this information to send the remaining representation data. Alternatively, they can cancel the upload entirely. Unlike ranged downloads, this protocol does not support transferring an upload as multiple requests in parallel. With resumable uploads, applications can recover from unintended interruptions. They can also interrupt an upload on purpose and resume it later, for example, when a user wants to pause the upload, the device's network connectivity changes, or bandwidth is needed for higher-priority tasks. This document introduces the concept of an upload resource to facilitate resumable uploads (). It defines new header fields to communicate the state of the upload (, , , and ) and the 104 (Upload Resumption Supported) status code to indicate the resource's support for resumable uploads (). It also defines the application/partial-upload media type to label partial representation data when resuming an upload ().

Conventions and Definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here. Some examples in this document contain long lines that are folded, as described in . This document uses the following terminology from to specify syntax and parsing: Item, Dictionary, Integer, and Boolean. This document uses the following terms from : "representation", "representation data", "representation metadata", "content", "client", and "server". This document uses the term "URI" as defined in . This document uses the term "patch document" from . An upload resource is a temporary resource on the server that facilitates the resumable upload of one representation (). A 104 interim response is an interim response with the 104 (Upload Resumption Supported) status code ().

Overview Resumable uploads are supported in HTTP by a temporary resource, an upload resource (), that is separate from the resource being uploaded to and specific to that upload. By interacting with the upload resource, a client can retrieve the current offset of the upload (), append to the upload (), and cancel the upload (). The remainder of this section uses examples to illustrate different interactions with the upload resource. HTTP message exchanges, and thereby resumable uploads, use representation data (see ). This means that resumable uploads can be used with many forms of content, such as static files, in-memory buffers, data from streaming sources, or on-demand generated data. Examples are purely illustrative and non-normative. Implementations follow the normative requirements in the other sections and the security considerations in .

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 (). 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 (). 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.

Upload Creation | | | | | Reserve resources | | for upload | |-----------------. | | | | |<----------------' | | | 104 Upload Resumption Supported | | Location: /uploads/abc | |<-------------------------------------------| | | X--------------Flow Interrupted--------------X ]]>

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 () from the upload resource.

Offset Retrieval | | | | 204 No Content | | Upload-Offset: X | |<------------------------------------------------| | | ]]>

3) The client can resume the upload by sending the remaining representation data to the upload resource (), 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.

Upload Append | | | | 200 OK | | Upload-Complete: ?1 | |<------------------------------------------------| | | ]]>

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

Upload Cancellation | | | | 204 No Content | |<------------------------------------------------| | | ]]>

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.

Upload Creation with Partial Representation Data | | | | 201 Created | | Location: /uploads/abc | |<------------------------------------------------| | | ]]>

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

Appending Partial Representation Data to Upload | | | | 204 No Content | |<------------------------------------------------| | | ]]>

3) If the connection was interrupted, the client might want to resume the upload, similar to the previous example (). The client retrieves the offset () 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.

Resuming an Interrupted Upload | | | | 204 No Content | | Upload-Offset: Y | |<------------------------------------------------| | | | PATCH /uploads/abc | | Upload-Complete: ?0 | | Upload-Offset: Y | | Content-Type: application/partial-upload | | | | [partial representation from offset Y] | |------------------------------------------------>| | | | 204 No Content | |<------------------------------------------------| | | ]]>

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.

Appending Remaining Representation Data | | | | 200 OK | | Upload-Complete: ?1 | |<------------------------------------------------| | | ]]>

Upload Resource A resumable upload is enabled through interaction with an upload resource. When a resumable upload begins, the server is asked to create an upload resource through a request to another resource (). Using this upload resource, the client can query the upload progress (), append representation data (), or cancel the upload (). The server is responsible for persisting the state of the upload resource (, , and ) and updating it as the upload progresses. Limits () can also apply to the upload resource. 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, keeping the upload resource available for a period of time after completion allows the client to verify the state of the upload if it did not receive the last response acknowledging the completion. Implementations are responsible for deciding whether they retain the resource and for what duration, considering the resource costs of doing so. 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 . The state of an upload consists of the following properties that are tracked by the server.

Offset The offset is the number of bytes from the representation data that have been processed, either during the creation of the upload resource () or by appending to it (). The offset is required when appending representation data () 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.

Upload-Offset The Upload-Offset request and response header field conveys the offset. It is an Item Structured Header Field (). Its value is a non-negative Integer () and indicates the current offset as viewed by the message sender. Other values MUST cause the entire header field to be ignored. The client can learn the current offset in three ways:

• The offset can be explicitly retrieved from the upload resource ().
• Interim responses for creating the upload () or appending (), and their final responses with a non-2xx status code and the Upload-Complete: ?0 header field, can include the Upload-Offset header field.
• Final responses for appending representation data () with a 2xx (Successful) status code and the Upload-Complete: ?0 header field acknowledge that the entire request content was received and the offset increased by the length of the appended representation data. If present, the Upload-Offset header field value MUST match this inferred offset.

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.

Upload-Complete The Upload-Complete request and response header field is an Item Structured Header Field (). Its value is a Boolean (); its meaning in requests and responses is described below. Other values MUST cause the entire header field to be ignored. An upload is marked as complete either when a request for creating the upload resource () or appending to it () includes the Upload-Complete header field set to true and the request content was fully processed, or when a response includes the Upload-Complete header field set to true. When used in an upload creation response () or an upload append response (), the Upload-Complete header field signals whether the response comes from the target resource of the initial request. The value of true means that the semantics of that resource apply, and the value of false means that the semantics of the resumable upload protocol apply. The client SHOULD NOT perform upload resumption to the upload resource after receiving a response with the Upload-Complete header field set to true. Note that the Upload-Complete header field can be true even when the full representation data was not transmitted in the case that the server decides to generate an early response when processing the targeted resource. Also note that it can be false in response to an invalid operation performed on a completed upload.

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 (). 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 () or appends to it () 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 () 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 of "https://iana.org/assignments/http-problem-types#inconsistent-upload-length" () 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 () to indicate that a request completes the upload. The offset could match the length, but the upload can still be incomplete.

Upload-Length The Upload-Length request and response header field is an Item Structured Header Field (). Its value is a non-negative Integer () and indicates the representation's length as a number of bytes. Other values MUST cause the entire header field to be ignored. The Upload-Length field can be used in response to an offset retrieval; see .

Upload Limits A server can limit an upload, for example, in its total size, in the size of each request, or in how long the upload resource remains available. The server announces these limits to the client in the Upload-Limit header field (), so the client can adhere to them. A client usually learns the limits when the upload resource is created (). It can learn them before that through an OPTIONS request ().

Upload-Limit The Upload-Limit response header field is a Dictionary Structured Header Field (). Its value is a Dictionary (). Other values MUST cause the entire header field to be ignored. Receivers of the Upload-Limit header field parse the Dictionary as described in . 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.

max-size The max-size limit specifies a maximum size, in bytes, for the representation data. The server might not create an upload resource if the representation's length () deduced from the upload creation request is larger than the maximum size. The server might also deactivate the upload resource if the offset () exceeds the maximum size. The value is an Integer.

min-size The min-size limit specifies a minimum size, in bytes, for the representation data. The server might not create an upload resource if the representation's length () deduced from the upload creation request is smaller than the minimum size or no length can be deduced at all. Resumable uploads impose additional overhead on the server, which might not be acceptable for small representations. Requests with representation data below this value might still be accepted by the server, although without the ability to resume them. The value is an Integer.

max-append-size The max-append-size limit specifies a maximum size, in bytes, for the request content in a single upload append () or upload creation () request. The server might reject requests exceeding this limit. A client that is aware of this limit MUST NOT send larger upload append or upload creation requests. The value is an Integer.

min-append-size The min-append-size limit specifies a minimum size, in bytes, for the request content in a single upload append () or upload creation () request. The server might reject requests below this limit. A client that is aware of this limit MUST NOT send smaller upload append or upload creation requests. The value is an Integer. This limit does not apply to upload creation requests with no content, or to requests completing the upload by including the Upload-Complete: ?1 header field.

max-age The max-age limit specifies the remaining lifetime, in seconds, of the upload resource, counted from the generation of the response. After the resource's lifetime is reached, the server might make the upload resource inaccessible. The value is an Integer.

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 (), 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 (), 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.

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 () and cancel the upload (). 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.

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 . Appending to an upload resource, as a series of appends, can be used to upload data up to the max-size limit () 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 () or append (), it SHOULD retry the request with a smaller size residing between min-append-size () and max-append-size (). If these limits are unknown at the time of receiving such a response, the client can attempt to discover them through an OPTIONS request (). 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.

Upload Creation

Client Behavior A client can start a resumable upload from any request that can carry content by including the Upload-Complete header field (). Any method that allows content can be used, such as POST, PUT, and PATCH. The request can benefit from incremental delivery; see . 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 (). 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 (), as described in . Clients are not required to discover limits () before starting the upload and might therefore be initially unaware of limits enforced by the server. However, the client SHOULD respect any limits () 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 () and cancel the upload (). If the client knows that the representation data is smaller than min-size (), 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 ) 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 ) can affect how servers act on the uploaded representation data. The Content-Type header field () indicates the media type of the representation. The Content-Encoding header field () names the content codings applied to the representation. The Content-Disposition header field () 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 (). 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 (). 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 to retry or resume the upload.

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 () 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 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 () and cancel the upload () if it does. The server SHOULD include the Upload-Complete header field () 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 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.

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

Offset Retrieval

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 () 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 (). The client MUST NOT retrieve the offset while it is still creating () or appending to () the same upload resource, because the server might terminate the in-progress request (). If the client receives a 2xx (Successful) response with a valid Upload-Offset header field, the client can continue appending representation data to it (). 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.

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 (),
• MUST indicate the limits in the Upload-Limit header field () if any, and
• SHOULD include the Cache-Control header field with the value no-store to prevent 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.

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.

Upload Append

Client Behavior A client can continue the upload and append representation data by sending a PATCH request with the application/partial-upload media type () to the upload resource. The request content is the representation data to append. The request can benefit from incremental delivery; see . 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 (), upload creation (), or upload append () 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 (). 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 to retry or resume the upload. Otherwise, the upload is considered a failure.

Server Behavior A server applies a PATCH request with the application/partial-upload media type () 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 . 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 (), 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 of "https://iana.org/assignments/http-problem-types#mismatching-upload-offset" (). 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 () 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 () 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 () after an offset retrieval () 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 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 () 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 for redirecting a response that completes the upload.

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: 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:

Upload Cancellation

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.

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

Example The following example shows an upload cancellation:

Concurrency Resumable uploads, as defined in this document, do not permit uploading representation data in parallel requests for the same upload. The client MUST NOT perform multiple representation data transfers for the same upload resource in parallel, or perform representation data transfers while the creation of the same upload resource is still in progress. Even if the client is well-behaved and does not send concurrent requests, network interruptions can occur in such a way that the client considers a request as failed while the server is unaware of the problem and considers the request still ongoing. The client might then try to resume the upload with the best intentions, resulting in concurrent requests from the server's perspective. Therefore, the server MUST take measures to prevent race conditions, data loss, and corruption from concurrent append () or cancellation () requests to the same upload resource. In addition, the server MUST NOT send outdated information in responses. This means that if a client appends at an offset from a final response (), the server MUST NOT reject that request for having the wrong offset, unless another append or a cancellation arrived in between. The RECOMMENDED approach is as follows: If a server receives a new request to retrieve the offset (), append representation data (), or cancel the upload () while a previous request for creating the upload () or appending representation data () to the same upload resource is still ongoing, the server SHOULD prevent race conditions, data loss, and corruption by terminating the previous request before processing the new request. Due to network delay and reordering, the server might still be receiving representation data from an ongoing transfer for the same upload resource, which from the client's perspective has failed. Since the client is not allowed to perform multiple transfers for the same upload resource in parallel, the server can assume that the previous attempt has already failed. Therefore, the server MAY abruptly terminate the previous HTTP connection or stream. Since implementing this approach is not always technically possible or feasible, other measures can be considered as well. A simpler approach is that the server only processes a new request to retrieve the offset (), append representation data (), or cancel the upload () once all previous requests have been processed. This effectively implements exclusive access to the upload resource through an access lock. However, since network interruptions can occur in ways that cause the request to hang from the server's perspective, it might take the server significant time to realize the interruption and time out the request. During this period, the client will be unable to access the resource and resume the upload, causing friction for the end users. Therefore, the recommended approach is to terminate previous requests to enable quick resumption of uploads.

Retry If the client receives a 4xx (Client Error) or 5xx (Server Error) response with the Upload-Complete header field set to false or missing when creating the upload resource () or appending to it (), it can apply the heuristics described below to retry or resume the upload.

• 409 (Conflict) with the Upload-Complete header field set to false: the upload can be resumed with the correct offset (). If no Upload-Offset header field is provided, the client SHOULD retrieve the offset () before resuming.
• 413 (Content Too Large): the upload can be resumed after applying appropriate limits ().
• 429 (Too Many Requests): the request can be retried after an appropriate delay.
• 5xx (Server Error): the request can be retried.

If no final response was received at all due to connectivity issues, the client MAY automatically attempt upload resumption by retrieving the current offset (). The client SHOULD limit the number of retries it performs before considering the upload a failure.

Status Code 104 (Upload Resumption Supported) The 104 (Upload Resumption Supported) status code can be used for two purposes:

• When responding to requests to create uploads, a 104 interim response can be sent to indicate the resource's support for resumable uploads, as well as the URI and limits of the corresponding upload resource in the Location and Upload-Limit header fields, respectively (see ). This notifies the client early about the ability to resume the upload in case of network interruptions.
• While processing the content of a request to append representation data or create an upload, the server can regularly send 104 interim responses to indicate the current upload progress in the Upload-Offset header field (see and ). This allows the client to show more accurate progress information about the amount of data processed by the server. In addition, clients can use this information to release representation data that was buffered, knowing that it does not have to be retransmitted.

When creating or appending resumable uploads, the client can generate a 100-continue expectation because it wants an indication that the resource is willing to accept the upload. The client MAY treat a 104 interim response as fulfilling the 100-continue expectation and start sending the request content. However, the server MUST NOT omit the 100 (Continue) response because it has sent a 104 interim response.

Media Type application/partial-upload The application/partial-upload media type describes a contiguous block from the representation data to be uploaded to a resource. There is no minimum block size and the block might be empty. The block can be a subset of the representation data, where the start and/or end of the block do not line up with the start and/or end of the representation data respectively.

Problem Types

Mismatching Offset This section defines the "https://iana.org/assignments/http-problem-types#mismatching-upload-offset" problem type . A server can use this problem type when responding to an upload append request () 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:

Inconsistent Length This section defines the "https://iana.org/assignments/http-problem-types#inconsistent-upload-length" problem type . A server can use this problem type when responding to an upload creation () or upload append request () to indicate that the request includes inconsistent length values, as described in . The following example shows a response:

Content Codings Since the codings listed in the Content-Encoding header field are a characteristic of the representation (see ), both the client and the server always compute the values for the Upload-Offset and optionally Upload-Length header fields on the content coded data (that is, the representation data). Moreover, the content codings are retained throughout the entire upload, meaning that the server is not required to decode the representation data to support resumable uploads.

Transfer Codings Unlike content codings (see ), transfer codings (see ) are a property of the message, not of the representation. Moreover, transfer codings can be applied in transit (e.g., by proxies). This means that a client does not have to consider the transfer codings to compute the upload offset, while a server is responsible for transfer decoding the message before computing the upload offset. The same applies to the Upload-Length header field value. See for how the Content-Length and Transfer-Encoding header fields interact.

Upload Strategies The definition of the upload creation request () 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 retransmission, and its knowledge about the resource's support for resumable uploads. The following subsections describe two typical upload strategies that are suited for common environments. Note that these strategies are never explicitly communicated to the server, and clients are not required to use only one strategy but can mix and adapt them to their needs.

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 ) before committing to work.

Upgrading to Resumable Uploads Optimistic upload creation allows clients and servers to automatically upgrade non-resumable uploads to resumable ones. In a non-resumable upload, the representation is transferred in a single request, usually POST or PUT, without any ability to resume from interruptions. The client can invite the server to upgrade such a request to a resumable upload by adding the Upload-Complete: ?1 header field to the original request. The Upload-Length header field SHOULD be added if the representation's length is known upfront. The request is not changed otherwise. If the target resource of the initial request supports resumable uploads, the server can create an upload resource and send its URI in a 104 interim response for the client to resume the upload after interruptions. A resource that does not support resumable uploads or does not want to upgrade to a resumable upload for this request ignores the Upload-Complete: ?1 header field. The transfer then falls back to a non-resumable upload without additional cost. This upgrade can also be performed transparently by a library or program that acts as an HTTP client by sending requests on behalf of a user. When the user instructs the client to send a non-resumable request, the client can perform the upgrade transparently and handle potential interruptions and resumptions under the hood without involving the user. The last response received by the client is considered the response for the entire upload and needs to be provided to the user.

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 () 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 (). 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.

Incremental Transfer, Processing, and Forwarding The resumable upload design is most effective when a server processes request message portions as they arrive, which ensures the greatest chance that data is processed before a possible transfer interruption. To support incremental processing, it is RECOMMENDED that clients send request content incrementally and minimize buffering. As described in , intermediaries might interfere with the incremental delivery of data to a server. Clients can use the Incremental header field defined in to signal their preference for incremental forwarding by intermediaries.

Request Cancellation A client or server might want to interrupt an in-flight message transfer intentionally for various reasons (see ). The mechanism to do so depends on the HTTP version in use:

HTTP/1.1:

close the underlying transport connection ()

HTTP/2:

reset the stream ()

HTTP/3:

abruptly terminate the request stream ()

Version-specific mechanisms place requirements on clients or servers for carrying out the cancellation. However, for all versions of HTTP, resumable uploads allow the server to process received representation data and expose the upload offset via the upload resource, enabling continuation of the upload after interruption.

Security Considerations

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 (). 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 ). URIs are also often logged or displayed by servers, proxies, and user agents, so the URI can be disclosed to third parties (see ).

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.

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.

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.

Resource Exhaustion Resumable uploads are vulnerable to Slowloris-style attacks . 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.

Message Size Limits Uploads performed as a series of appends can be used to upload data up to the max-size limit (), 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.

Different Origins The target resource of the initial request () and the upload resource might have different origins (). 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 (), 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 and do not apply in this case.

IANA Considerations

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

Field Name	Status	Structured Type	Reference
Upload-Offset	permanent	Item	of RFC nnnn
Upload-Complete	permanent	Item	of RFC nnnn
Upload-Length	permanent	Item	of RFC nnnn
Upload-Limit	permanent	Dictionary	of RFC nnnn

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:

of RFC nnnn

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 of RFC nnnn

Interoperability considerations:

N/A

Published specification:

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

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:

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:

of RFC nnnn

References Normative References The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document describes the overall architecture of HTTP, establishes common terminology, and defines aspects of the protocol that are shared by all versions. In this definition are core protocol elements, extensibility mechanisms, and the "http" and "https" Uniform Resource Identifier (URI) schemes. This document updates RFC 3864 and obsoletes RFCs 2818, 7231, 7232, 7233, 7235, 7538, 7615, 7694, and portions of 7230. The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document defines HTTP caches and the associated header fields that control cache behavior or indicate cacheable response messages. This document obsoletes RFC 7234. The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document specifies the HTTP/1.1 message syntax, message parsing, connection management, and related security concerns. This document obsoletes portions of RFC 7230. This specification describes an optimized expression of the semantics of the Hypertext Transfer Protocol (HTTP), referred to as HTTP version 2 (HTTP/2). HTTP/2 enables a more efficient use of network resources and a reduced latency by introducing field compression and allowing multiple concurrent exchanges on the same connection. This document obsoletes RFCs 7540 and 8740. The QUIC transport protocol has several features that are desirable in a transport for HTTP, such as stream multiplexing, per-stream flow control, and low-latency connection establishment. This document describes a mapping of HTTP semantics over QUIC. This document also identifies HTTP/2 features that are subsumed by QUIC and describes how HTTP/2 extensions can be ported to HTTP/3. This document describes a set of data types and associated algorithms that are intended to make it easier and safer to define and handle HTTP header and trailer fields, known as "Structured Fields", "Structured Headers", or "Structured Trailers". It is intended for use by specifications of new HTTP fields. This document obsoletes RFC 8941. Several applications extending the Hypertext Transfer Protocol (HTTP) require a feature to do partial resource modification. The existing HTTP PUT method only allows a complete replacement of a document. This proposal adds a new HTTP method, PATCH, to modify an existing HTTP resource. [STANDARDS-TRACK] This document defines a "problem detail" to carry machine-readable details of errors in HTTP response content to avoid the need to define new error response formats for HTTP APIs. This document obsoletes RFC 7807. RFC 2616 defines the Content-Disposition response header field, but points out that it is not part of the HTTP/1.1 Standard. This specification takes over the definition and registration of Content-Disposition, as used in HTTP, and clarifies internationalization aspects. [STANDARDS-TRACK] In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Informative References This document defines two strategies for handling long lines in width-bounded text content. One strategy, called the "single backslash" strategy, is based on the historical use of a single backslash ('\') character to indicate where line-folding has occurred, with the continuation occurring with the first character that is not a space character (' ') on the next line. The second strategy, called the "double backslash" strategy, extends the first strategy by adding a second backslash character to identify where the continuation begins and is thereby able to handle cases not supported by the first strategy. Both strategies use a self-describing header enabling automated reconstitution of the original content. This document specifies the "Incremental" HTTP header field, which instructs HTTP intermediaries to forward the HTTP message incrementally. This document defines the concept of an "origin", which is often used as the scope of authority or privilege by user agents. Typically, user agents isolate content retrieved from different origins to prevent malicious web site operators from interfering with the operation of benign web sites. In addition to outlining the principles that underlie the concept of origin, this document details how to determine the origin of a URI and how to serialize an origin into a string. It also defines an HTTP header field, named "Origin", that indicates which origins are associated with an HTTP request. [STANDARDS-TRACK]

Changes

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.

Draft Version Identification To assist the development of implementations and interoperability testing while this document is still a draft, an interop version is defined. Implementations of this draft use the interop version to identify the iteration of the draft that they implement. The interop version is bumped for breaking changes. The current interop version is 10. Client implementations of draft versions of the protocol MUST send a header field Upload-Draft-Interop-Version with the interop version as its value to its requests. The Upload-Draft-Interop-Version field value is an Integer. Server implementations of draft versions of the protocol MUST NOT send a 104 (Upload Resumption Supported) interim response when the interop version indicated by the Upload-Draft-Interop-Version header field in the request is missing or mismatching. Server implementations of draft versions of the protocol MUST also send a header field Upload-Draft-Interop-Version with the interop version as its value to the 104 (Upload Resumption Supported) interim response. Client implementations of draft versions of the protocol MUST ignore a 104 (Upload Resumption Supported) interim response with missing or mismatching interop version indicated by the Upload-Draft-Interop-Version header field. The reason both the client and the server are sending and checking the draft version is to ensure that implementations of the final RFC will not accidentally interop with draft implementations, as they will not check the existence of the Upload-Draft-Interop-Version header field.

Acknowledgments This document is based on an Internet-Draft specification written by Jiten Mehta, Stefan Matsson, and the authors of this document. The tus v1 protocol is a specification for a resumable file upload protocol over HTTP. It inspired the early design of this protocol. Members of the tus community helped significantly in the process of bringing this work to the IETF. The authors would like to thank Mark Nottingham for substantive contributions to the text, along with the following in alphabetical order for their thorough reviews of the document:

• Daniel Resnick
• Glenn Strauss
• Grant Gryczan
• Julian Reschke
• Mert Alev
• Mike Bishop
• Roy T. Fielding
• Willy Tarreau