RESUMABLE: Early response handling

[guoye-zhang]

It was brought up in #3275 that Upload-Complete in the response might not match the request due to the possibility of early responses.

Should Upload-Complete be true in the response if the server wants to terminate an incomplete upload (early response from the original resource)? Or when HTTP is used for bidirectional streaming.

[GrantGryczan]

I think this is definitely useful, but needs to be handled carefully. Without this, clients often have no means of distinguishing whether an error response relates to the original resource or the upload resource.

I was actually just about to submit an issue going over how I'd approach specifying the requirements around this. I'll just add it as a comment here instead, once I finish writing it.

[guoye-zhang]

I tagged this "discuss" to talk about during IETF 125

[GrantGryczan]

@guoye-zhang pointed out the following in #3275 (comment), in relation to early error responses:

We generally use Upload-Complete: ?1 to distinguish between the final response and the intermediate responses from the resumable upload protocol.

If this is the case, it's important to have specific normative language on the usage of headers in early responses. For example, this would allow clients to distinguish between an error response relating to the original resource vs. the upload resource. It would also facilitate clients receiving more information that they can use to reduce round trips when handling errors or deciding whether and how to retry. See #3275 (comment) for examples of how clients could use headers to handle error responses.

I'd propose the following, which I'm happy to refine and organize into a PR if desirable (though it'll have to be towards the end of the month).

---

For 4xx responses to creation requests:

• If the request failed because it violated upload limits, then the response SHOULD include Upload-Limit.
• If the upload was completed, and no upload resource was created, then the response SHOULD include Upload-Complete: ?1 and MUST NOT include Upload-Offset.
  • Note that servers that don't support resumable uploads won't include Upload-Complete. Nevertheless, it helps clients when possible.
  • See RESUMABLE: Clarify client recovery behavior for 409 Conflict responses #3275 (comment) for rationale on "MUST NOT" (in particular simplifying client logic and mitigating erroneous infinite retries).
• If the upload was completed, and an upload resource was created, then the response MUST include Upload-Complete: ?1 and MUST NOT include Upload-Offset.
  • This can be a hard requirement since successful upload resource completion necessarily implies the part of the server generating this response is aware of resumable uploads. Note that append responses already require this (section 4.4.2).
  • Same as previous rationale for "MUST NOT".
• If the upload was not completed, and no upload resource was created, then the response SHOULD include Upload-Complete: ?1 and MUST NOT include Upload-Offset.
  • See RESUMABLE: Clarify client recovery behavior for 409 Conflict responses #3275 (comment) for (different) rationale on "MUST NOT".
• If the upload was not completed, and an upload resource was created and not deactivated, then the response SHOULD include Upload-Complete: ?0 and SHOULD include Upload-Offset.
• If the upload was not completed, and an upload resource was created and deactivated, then the response MUST include Upload-Complete: ?1 and MUST NOT include Upload-Offset.
  • This can be a hard requirement since upload resource deactivation necessarily implies the part of the server generating this response is aware of resumable uploads.
  • Same as previous rationale for "MUST NOT".

For 4xx responses to append requests:

• If the request failed because it violated upload limits, then the response SHOULD include Upload-Limit.
• If the upload was completed, then the response MUST include Upload-Complete: ?1 and, unless it's a 409 offset mismatch response, MUST NOT include Upload-Offset.
  • The "MUST include" is already a requirement from section 4.4.2.
  • See RESUMABLE: Clarify client recovery behavior for 409 Conflict responses #3275 (comment) for rationale on "MUST NOT".
• If the upload was not completed, and the upload resource is still activated, then the response SHOULD include Upload-Complete: ?0 and SHOULD include Upload-Offset.
• If the upload was not completed, and the upload resource was deactivated, then the response MUST include Upload-Complete: ?1 and, unless it's a 409 offset mismatch response, MUST NOT include Upload-Offset.
  • Same rationales as the last point under creation responses.
  • "it's a 409 mismatch response" might not be possible here, but I'm including it for clarity just in case.

Despite the verbosity of all of the above, I expect the implementation to be very simple, since it mostly boils down to just including whatever information the server has on the upload in the response. I also wouldn't be surprised if some statements can be consolidated.

5xx responses are exceptionally likely to be returned from a part of the server unaware of resumable uploads, even as a result of internal errors arising directly from resumable uploads, so they should follow the same as all of the above, but with each "MUST include" treated as "SHOULD include". Note that this (intentionally) loosens the current section 4.4.2 requirement, which I'd argue isn't realistic for 5xx responses.

The current draft already covers 2xx responses well enough. Phrasing just needs to be expanded to allow them to be returned before the client marks the upload as completed.

I think all early 1xx responses can just be transparently passed on with no changes, since clients can easily distinguish an early 1xx response by whether it's 104. The spec probably just needs to clarify 1xx responses are allowed.

I believe early 3xx responses don't make sense, since semantically, that would tell the client to restart or continue the upload at the new location, which is already what non-early 3xx responses do. So I don't think anything needs to be added for 3xx.

---

The reason to use "SHOULD"s rather than "MUST"s is that in those situations, unfortunately, responses may be returned from a part of the server which isn't aware of resumable uploads. The draft already covers some situations where the server is certainly aware of resumable uploads in an error response, such as here and here, and those do use "MUST" rather than "SHOULD" as expected. It may be useful to rephrase things to avoid server implementers interpreting these "SHOULD"s for error responses in general as conflicting with the "MUST" for the specific kind of 409 response described in section 4.4.2.

The reason to use "SHOULD"s rather than "MAY"s (and, where possible, "MUST"s rather than "SHOULD"s) is simply that more information is better for clients, and arguably, clients are going to need all the information they can get. (See the last paragraph of this comment for more on that.)

Other more trivial changes would likely be necessary to support early responses, such as in section 4.1.2 on completeness, allowing servers to mark an upload as complete before the client does. This may require distinguishing between "fully complete" and "early complete", or something like that. Not sure.

Lastly, it's equally important to get the specifics right on how clients should handle these responses. Unfortunately, I don't see any possible way to allow clients to certainly distinguish, in every situation, whether the response is related to the resumable upload itself or the processing of the upload representation. As far as I know, the most we can do is recommend servers give the client as much information as possible (as I outlined above). I'd elaborate on best-effort heuristics that I think would be wise to recommend, but I'm out of time for now. Perhaps another time, but #3275 (comment) is a good starting point.

[Acconut]

Thank you for the detailed response, @GrantGryczan! Overall, an approach that doesn't use the presence of the Upload-Offset header field to determine the response semantics would be preferable. Otherwise the semantics depend on the status code, Upload-Complete and Upload-Offset header fields. If I understand correctly, the distinction is only necessary for status codes that have a special meaning in the upload process itself, but I believe there are other alternatives as well for handling these (see #3275 (comment)).

When starting an upload, the client's next step in the case of a 4XX also depends on whether the client knows that the resource supports resumable uploads. If so, any response missing Upload-Complete can be interpreted as a failure of the upload process itself. Depending on the resource, it might be safe to just retry, but that is application-specific. If the client optimistically upgrades an upload to resumable, such a response would have to be counted as the final response for the upload.

[GrantGryczan]

I agree that the reliance on a response header isn't ideal! I thought of using a new 4xx code, but I dismissed the idea because I'm not sure how feasible that is. I had the feeling that 4xx codes are scarce. But if not, I think that would be an excellent solution to have more well-defined semantics, simplify implementations, and loosen unintuitive requirements.