Skip to content
Open
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions draft-ietf-httpbis-resumable-upload.md
Original file line number Diff line number Diff line change
Expand Up @@ -351,10 +351,10 @@ The following key-value pairs are defined:
: Specifies a minimum size for the representation data, counted in bytes. The server might not create an upload resource if the length ({{upload-length}}) deduced from the upload creation request is smaller than the minimum size or no length can be deduced at all. The value is an Integer.

`max-append-size`:
: Specifies a maximum size counted in bytes for the request content in a single upload append request ({{upload-appending}}). The server might reject requests exceeding this limit. A client that is aware of this limit MUST NOT send larger upload append requests. The value is an Integer.
: Specifies a maximum size counted in bytes for the request content in a single upload append ({{upload-appending}}) or upload creation ({{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`:
: Specifies a minimum size counted in bytes for the request content in a single upload append request ({{upload-appending}}). The server might reject requests below this limit. A client that is aware of this limit MUST NOT send smaller upload append requests. The value is an Integer. Requests completing the upload by including the `Upload-Complete: ?1` header field are exempt from this limit.
: Specifies a minimum size counted in bytes for the request content in a single upload append ({{upload-appending}}) or upload creation ({{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. Requests completing the upload by including the `Upload-Complete: ?1` header field are exempt from this limit.

`max-age`:
: Specifies the remaining lifetime of the upload resource in seconds counted from the generation of the response. After the resource's lifetime is reached, the server might make the upload resource inaccessible and a client SHOULD NOT attempt to access the upload resource as these requests will likely fail. The value is an Integer.
Expand All @@ -367,7 +367,9 @@ A server that supports the creation of a resumable upload resource ({{upload-cre

A client can use an `OPTIONS` request to discover support for resumable uploads and potential limits before creating an upload resource. While the values `*/*` and `application/*` in the `Accept-Patch` response header field indicate the acceptance of the `application/partial-upload` in PATCH requests, it does not necessarily indicate support for all aspects of resumable uploads as defined in this document. 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 1GB, but reduce it to 100MB when the media type indicates an image.

Servers, including intermediaries, can (and often do) apply restrictions on the size of individual request message content. There is no standard mechanism to communicate such existing size restriction. A server that implements one can respond with a 413 Content Too Large status code; see {{Section 15.5.14 of HTTP}}. Appending to an upload resource, as a series of appends, can be used to upload data up to the `max-size` limit without encountering per-message limits. The `min-append-size` and `max-append-size` limits apply to the upload resource. Servers might apply restrictions that are smaller than the append limits, which would also result in a failed request. Clients could deal with such situations by retrying an upload append using a smaller size, as long as the new size resides between `min-append-size` and `max-append-size`. Cases where an append uses `min-append-size` yet fails with a 413 Content Too Large response might indicate a deployment mismatch that cannot be recovered from.
Servers, including intermediaries, can (and often do) apply restrictions on the size of individual request message content. There is no standard mechanism to communicate such existing size restriction. A server that implements one can respond with a 413 Content Too Large status code; see {{Section 15.5.14 of HTTP}}. Appending to an upload resource, as a series of appends, can be used to upload data up to the `max-size` limit 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 ({{upload-creation}}) or append ({{upload-appending}}), 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 SHOULD attempt to discover them through an `OPTIONS` request. Cases where a request uses `min-append-size` yet fails with a 413 Content Too Large response might indicate a deployment mismatch that cannot be recovered from.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should probably require 413 to carry an Upload-Limit header if it's from a resumable upload server. Upload creation can be attempted without knowledge of server support, and clients can't retry a non-resumable upload.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The issue is that a proxy might respond with 413 based on the request's Content-Length, so even if the server is resumable it can't add the header in this case.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The OPTIONS request to learn the limits also doubles as a way to discover resumability. Maybe it should be emphasized here more, so as to avoid retrying without knowing about resumability.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As an implementor of a generic HTTP client, we can attempt resumable uploads for all uploads since it has little overhead and minimum risk, but we cannot perform an OPTIONS discovery step for all uploads that fail with 413. We need to know that the other side supports resumable uploads before doing something expensive.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The OPTIONS request wouldn't be a MUST - it's more that they MUST NOT retry if they don't know the server supports resumability. I suppose the only other way for a generic library to handle this proxy scenario would be to configure it to assume the server is resumable.

Copy link
Contributor

@guoye-zhang guoye-zhang Oct 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

SHOULD is a recommendation and means that we think it's a good idea. I don't think it's feasible for us since you know there are unupgradable printers that would crash when it receives an OPTIONS request. We have to be as safe as possible when discovering resumable upload support.

Yeah, this has to be an opt-in feature, although a more desirable opt-in behavior probably is to always send OPTIONS to detect Upload-Limit first instead of relying on 413.

Copy link
Author

@mertalev mertalev Oct 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That makes sense. To summarize:

  • If 413 contains Upload-Limit header, the client SHOULD try again within these limits
  • If not, the client MAY try OPTIONS to learn limits and try again
  • Client MUST NOT retry if it isn't aware of server resumable upload support, either from the above or from prior knowledge

Do those changes sound good?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, looks good. I believe the reason we didn't tackle upload creation originally was the complexity of its interaction with discovery. Upload appending can only be performed if the server support is confirmed so its behavior is easier to define.

Minor nit: we stopped using the phrase "prior knowledge" based on the feedback in #3215.


## Upload Creation {#upload-creation}

Expand Down