]>

chris.s.martinez@outlook.com

partial upload range http The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document defines partial content uploads, which allows a client to upload content, such as a large file, via multiple requests. This document also outlines the metadata header fields for indicating state changes, request header fields for making preconditions on such state, and the rules for constructing the responses. About This Document Status information for this document may be found at . Source for this draft and an issue tracker can be found at .

Introduction Hypertext Transfer Protocol (HTTP) clients often encounter interrupted data transfers because of canceled requests or dropped connections. Section 14 of defines HTTP range requests and partial responses, but it only describes how a client can transfer data from a server (e.g. download). This document defines a reciprocal set of HTTP range requests and responses that a client can use to transfer data to a server (e.g. upload). Where appropriate, this document will use existing range units and header fields defined in , , and . Although the range request mechanism is designed to allow for extensible range types, this specification only defines requests for byte ranges.

Terminology 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. This specification defines conformance criteria for both senders (usually, HTTP user agents) and recipients (usually, HTTP origin servers). An implementation is considered conformant if it complies with all the requirements associated with its role.

Syntax Notation This specification uses the Augmented Backus-Naur Form (ABNF) notation of with a list extension, defined in Section 2.1 of , that allows for compact definition of comma-separated lists using a '#' operator (similar to how the '*' operator indicates repetition).

New Partial Content Upload The POST method MUST be used to indicate that the client intends to start a new partial content upload. The client MUST send the Content-Disposition header field defined in to indicate how the origin server is expected process the content. This will provide enough information for the origin server to allocate the requested storage space before any content is uploaded. This behavior ensures that the origin server has enough storage space and the client is authorized to upload the content. If the origin server successfully allocates the necessary storage, it MUST respond with 201 (Created), including a Location and ETag header field. A server MAY elect to return the Allow-Length header field, which indicates the maximum allowed length of any subsequent partial content. If an origin server refuses to allocate the requested storage (ex: due to policy limit), it MUST respond with 422 (Unprocessable Content). It is RECOMMENDED that such a response include problem details as defined in which explains why the content cannot be allocated. When an origin server fails to allocate storage for the resource, then it MUST respond with 507 (Insufficient Storage). If the client is not authorized to create the requested resource, the origin server MUST respond with 401 (Unauthorized) if authentication is possible; otherwise, it MUST respond with 403 (Forbidden). There is no temporal specification as to how long a client is allowed take to upload all the content ranges. A server MAY choose to implicitly cancel an upload it deems abandoned due to inactivity after an arbitrary period or after an absolute amount of time has passed. It is RECOMMENDED that an origin server which knows when the upload will be considered canceled return the Sunset header as defined in , which indicates the cancellation date and time. describes how an upload is explicitly canceled.

The Content-Disposition Header Field Content-Disposition is a REQUIRED header field. In its absence, the origin server MUST respond with 400 (Bad Request). This header field indicates that the origin server is to create a new storage resource and of what size.

The Create Disposition Type The disposition type "create" is REQUIRED and is meant to instruct the origin server that it SHOULD preallocate the specified storage space, but the request itself does not contain a body that is to be written to storage. If a client were to send one of the existing disposition types "inline" or "attachment" to an origin server without a body, it is not clear what action the server MUST take. The disposition type "create" expresses a client's expectation that the disposition of the origin server is to create a resource of "size" octets.

Disposition Parameter: 'Size' The size parameter is REQUIRED and has the same meaning as defined in Section 2.7 of . The origin server MUST use this value as the amount of storage to allocate in octets. If a client does not provide the size parameter or the size is equal to or less than zero, the origin server MUST respond with 411 (Length Required). If the origin server refuses to allocate the requested storage, it MUST respond with 422 (Unprocessable Content). It is RECOMMENDED that such a response include problem details as defined in which explains why the content cannot be allocated and includes the maximum allowable size. For example, if the requested size is too large, the server MAY respond with:

Disposition Parameter: 'Filename' The "filename" and "filename*" parameters are OPTIONAL parameters that have the same meaning defined in Section 4.3 of . When specified by a client, the origin server MAY use the specified file name in lieu of the resource identifier that it elects to generate, which MAY also derive from the request URL.

Disposition Parameter: 'Modification-Date' The modification-date parameter is OPTIONAL and has the same meaning as defined in Section 2.5 of . When the client does not specify the modification-date parameter, the current date and time on the origin server MAY be used if the server has a clock.

The Allow-Length Header Field The Allow-Length response header field allows a server to communicate the allowable length of content. It provides information to clients that enables them to delimit framing as they send partial content to the server. It is RECOMMENDED that an origin server return the Allow-Length header field when a resource is provisioned for an upload. An example is In the absence of the Allow-Length header field, a client is obligated to know the maximum length allowed through out-of-band knowledge such as a publicly documented policy or through probing requests until a suitable length is determined. An origin server MAY choose to return Allow-Length in a HEAD or OPTIONS request for a client that did not persist the value and resumes an upload at a later time. The specified Allow-Length SHOULD NOT change for the lifetime of an upload. If the value does change during an upload, then the origin server SHOULD support the HEAD method, OPTIONS method, or both, that SHALL respond with an updated Allow-Length header field.

Resource Contention It is possible that multiple clients MAY request an origin server provision storage for the same resource. An origin server SHOULD use optimistic behavior such that the last successful client request is the owner of the remaining upload requests. The entity tag returned by the origin server in the response provides the correlation to all other requests for a given client. If the server is unable to fulfill the request because the resource cannot be provisioned, it MUST respond with 409 (Conflict) to which a client MAY retry the request. A server MAY also return the Retry-After header field as defined in Section 10.2.3 of to provide a hint to the client as to how long it SHOULD wait before retrying the request. It is NOT RECOMMENDED that origin servers employ a stateful locking strategy as it could result in a condition by which no client is able to create the requested resource. This document does not describe how to lock or unlock such a resource.

Entity Tags Upon successful allocation of the requested storage space, the origin server MUST return an entity tag in the response. The entity tag MUST be used for all subsequent requests, including canceling the entire upload. All entity tags returned by the origin server SHOULD use strong validation.

Resource Retrieval An origin server which supports partial content uploads MAY also support requesting that same resource for downloads. An origin server that implements this capability MUST NOT allow GET requests, in part or in whole, to the provisioned resource until all the corresponding resource content has been uploaded to the origin server. The origin server MUST respond with 404 (Not Found) for any resource that has not been completely uploaded.

Example Here is an example of a POST request to initiate a new partial content upload: An example response would be: Sunset: Mon, 13 Nov 2023 00:00:00 GMT ]]>

Update Partial Content Upload The PATCH method MUST be used to update partial content. Unlike other uses of PATCH, an origin server MUST complete this operation idempotently. Given the entity tag provided by the client and the fact that the necessary storage space has already been allocated, the origin server has enough information to safely fulfill the request idempotently. This behavior is true even if multiple client requests occur concurrently or overlap in content range. If the origin server successfully updates the specified content range and more content is expected, then it MUST respond with 202 (Accepted); otherwise, the server MUST complete the upload as described in . If the Content-Disposition header field contained the modification-date parameter, then the origin server MUST also return this value in the response Last-Modified header field.

Content-Range Header Field Content-Range is a REQUIRED header field that has the same meaning as defined in Section 14.4 of . The Content-Range header field informs the origin server what part of the content is being uploaded. If the byte-range in Content-Range is invalid or the complete-length does not match the provisioned storage amount defined by the size parameter in the Content-Disposition header field when the partial content upload was started, the server MUST respond with 416 (Range Not Satisfiable). A client SHOULD inspect the complete-length of the Content-Range header field in the error response to determine whether the source content has been modified.

Last-Modified Header Field Last-Modified is an OPTIONAL header field and has the same meaning as defined in Section 8.8.2 of . If the modification-date parameter was specified in the Content-Disposition header field as part of the start of the partial content upload, then the origin server MUST respond with the Last-Modified header field containing the same value. A client MAY use the Last-Modified header field to determine whether its copy of the content being uploaded is still the same as the copy the origin server has.

If-Match Header Field If-Match is a REQUIRED header field. The If-Match header field MUST contain the entity tag returned by the origin server when the partial content upload was started. If a client does not specify the If-Match header field, the server MUST respond with 428 (Precondition Required). If the entity tag specified by the client does not match the value known to the server, the server MUST respond with 412 (Precondition Failed).

Expect Header Field Expect is an OPTIONAL header field and has the same meaning as defined in Section 10.1.1 of . It is still possible for partial content uploads to be large. Clients SHOULD send the 100-Continue expectation to ensure that the server is willing to accept the size of the content being sent. If the client sends more partial content than the server is willing to accept in a single request, it MUST respond with 413 (Payload Too Large). The server SHOULD also respond with the Allow-Length header field () to indicate the maximum length allowed by the server.

Resource Contention It is possible that multiple clients MAY request that an origin server update a partial content upload for the same resource. Provided that the If-Match header field contains a valid entity tag (), an origin server SHOULD use an optimistic behavior when copying the uploaded content to storage. If the server is unable to fulfill the request because the resource is inaccessible, it MUST respond with 409 (Conflict). Since the request MUST be idempotent, a client MAY retry a 409 error response. A server MAY also return the Retry-After header field as defined in Section 10.2.3 of to provide a hint to the client as to how long it SHOULD wait before retrying the request. If the server is unable to fulfill the request because the allocated storage for the resource no longer exists, the server MUST respond with 410 (Gone). Retrying large content uploads MAY strain network resources and are likely to have high latency. If the origin server is aware that the storage resource is temporarily unavailable, it is RECOMMENDED that it automatically retry copying the uploaded content. The number of times the server retries, or whether that server retries at all, is at the discretion of the server.

Completing the Upload To complete an upload, a client MUST send all the corresponding content ranges. A client MAY vary the size of each upload; for example, it MAY increase or decrease the content range based on available network bandwidth. A server knows that the upload is complete when it has received uploads from a client that contain all of the contiguous content ranges up to the size of the total content, potentially overlapping. If the origin server determines no further content is expected, then it MUST respond with 201 (Created) and Content-Location. Content-Location indicates the URL where the client MAY retrieve the resource with a GET request, which MAY not previously be known to the client. A server SHOULD NOT be stateful. A server, however, MAY choose to store the start and end position of each content range received in external storage such as a file or database. The exact mechanism used to implement this behavior is at the discretion of the server. Once the server has made the decision that all of the content has been uploaded, it MAY allow access to the resource via the GET method that is indicated in Content-Location.

Example Here is an example of a PATCH request which uploads part of an upload: ... ]]>

Cancel Partial Content Upload The DELETE method MUST be used to cancel a partial content upload. When a client requests that a partial content upload be canceled, the server MUST deallocate the storage previously provisioned for the upload. Only the client originator MAY cancel the content upload. The same client or a new client MAY begin a new partial content upload before the existing upload is complete. Starting a new partial content upload intrinsically cancels any existing upload.

If-Match Header Field If-Match is a REQUIRED header field. The If-Match header field MUST contain the entity tag returned by the origin server when the partial content upload was started. If a client does not specify the If-Match header field, the server MUST respond with 428 (Precondition Required). If the entity tag specified by the client does not match the value known to the server, the server MUST respond with 412 (Precondition Failed).

Resource Contention It is possible that multiple clients MAY request that an origin server cancel a partial content upload for the same resource. If the server is unable to fulfill the request because the resource is inaccessible, it MUST respond with 409 (Conflict). Since the request MUST be idempotent, a client MAY retry a 409 error response. A server MAY also return the Retry-After header field as defined in Section 10.2.3 of to provide a hint to the client as to how long it SHOULD wait before retrying the request. If the server is unable to fulfill the request because the allocated storage for the resource no longer exists, the server MUST respond with 204 (No Content) because the upload has already been canceled.

Example Here is an example of canceling an upload:

Get Partial Content Upload Metadata There are situations where a client does not have the necessary information to continue uploading content. A few of these scenarios include a client losing network connectivity, pausing or suspending uploads, and resuming or retrying an upload where the previously uploaded content ranges were not persisted by the client. These scenarios MAY lead a client to request from the destination origin server what information has been already uploaded to it. The HEAD method MUST be used to request the metadata about a partial content upload. If the partial content upload metadata is successfully retrieved, the server MUST respond with 204 (No Content). If the server is unable to fulfill the request because the resource no longer exists and the server was previously aware of the resource, the server SHOULD respond with 410 (Gone). The origin server MUST, otherwise, respond with 404 (Not Found) for any resource that does not exist.

Allow-Length Header Field Allow-Length is an OPTIONAL response header field. It informs the client what the current content size limit is for any partial upload, which MAY be different from the limit reported in any previous response. It is RECOMMENDED that an origin server return the Allow-Length header field with an appropriate value, even when a limit had not been previously set.

Content-Length Header Field Content-Length is a REQUIRED response header field. The Content-Length value MUST correspond to the size parameter specified in the original Content-Disposition header field when the partial content upload was created.

ETag Header Field ETag is a REQUIRED response header field. The ETag value MUST be the same value generated by the server when the partial content upload was created.

Last-Modified Header Field Last-Modified is an OPTIONAL response header field. The Last-Modified header field MUST be returned if the modification-date parameter was specified in the original Content-Disposition header field when the partial content upload was created.

Sunset Header Field Sunset is an OPTIONAL response header field. If the server imposes a temporal limit on how much time a client has before it considers the upload abandoned, the server MUST return the Sunset header field containing the absolute date and time that will occur. Any date and time returned by the server SHOULD be the same value returned when the partial content upload was created.

Range Header Field Range is an OPTIONAL response header field. The server indicates what content the client has already uploaded by sending the Range header field as defined in Section 14.2 of . Each range specified MUST use the byte-range unit type as defined by Section 14.1.2 of with the exception that the first-pos and last-pos values MUST both be specified. A server MAY chose to emit a Range header field for each byte offset range or collapse them into multiple header field values. A server MAY also merge overlapping ranges in order to reduce the number of reported range values. As an example, if a client previously made 3 partial uploads and with overlapping ranges, the server can emit: Or:

Example Here is an example of a response to a HEAD request which reports the metadata for a partial content upload that is in progress:

Security Considerations This document has the same security considerations that are outlined in Section 5 of and Section 7 of . There are additional risks from clients requesting unintentionally large resources. and describe the validation process and how to reject such a request. The maximum sizes allowed, in whole or in part, are at the discretion of the origin server. While this document mandates that entity tags be used in requests, it does not dictate the format or content of those values. An origin server SHOULD generate an entity tag that cannot be easily replayed. A few possible techniques might include rotating the entity tag during each request as well as encrypting or signing a value in the entity tag using a client certificate. These protective measures would be in addition to transport-level security, client authentication, and client authorization.

IANA Considerations

The Create Disposition Type This document registers a new "disposition-type" value for the Content-Disposition header: create. The definition and usage of this value is described in . IANA is asked to add a new "disposition-type" value to the Content-Disposition header as defined by : create: allocate a resource of "size" octets without a body The "size" parameter is REQUIRED. The "filename", "creation-date", "modification-date", and "read-date" are OPTIONAL. Any other parameters are unused and SHOULD be ignored.

The Allow-Length Response Header Field This document requests that the Allow-Length response header field be added to the "Permanent Message Header Field Names" registry (see ), taking into account the guidelines given by . Header Field Name: Allow-Length Protocol: http Status: standard Author/Change controller: IETF

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. This specification defines the Sunset HTTP response header field, which indicates that a URI is likely to become unresponsive at a specified point in the future. It also defines a sunset link relation type that allows linking to resources providing information about an upcoming resource or service sunset. 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] Internet technical specifications often need to define a formal syntax. Over the years, a modified version of Backus-Naur Form (BNF), called Augmented BNF (ABNF), has been popular among many Internet specifications. The current specification documents ABNF. It balances compactness and simplicity with reasonable representational power. The differences between standard BNF and ABNF involve naming rules, repetition, alternatives, order-independence, and value ranges. This specification also supplies additional rule definitions and encoding for a core lexical analyzer of the type common to several Internet specifications. [STANDARDS-TRACK] This specification defines registration procedures for the message header fields used by Internet mail, HTTP, Netnews and other applications. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. This memo provides a mechanism whereby messages conforming to the MIME specifications [RFC 2045, RFC 2046, RFC 2047, RFC 2048, RFC 2049] can convey presentational information. It specifies the "Content- Disposition" header field, which is optional and valid for any MIME entity ("message" or "body part"). [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 Web Hypertext Application Technology Working Group

Appendix A. Content-Disposition Versus Content-Length The Content-Length header field defined in Section 8.6 of is the most appropriate header field to indicate the size of the intended content being uploaded. As Section 8 of indicates, a "representation" can be anything. In this document, the "representation" would be the allocated storage for the content to be uploaded, such as a file. The client scripting engines of modern browsers use the XMLHttpRequest (XHR) API and Fetch Standard. Section 4.5.2 in the specification and Section 2.2.2 in the specification both state that the Content-Length header is restricted and is only allowed to be set by the browser. The inability to set the Content-Length header without a body makes it an unusable header field as it relates to this document. In lieu of defining a new header field, this document elected to use the existing Content-Disposition header field defined in and to serve the same purpose.

Acknowledgements The author would like to thank James Zimmerman, Hongtao Chen, and Xavier John for their valuable contributions and reviews.