Resumable upload: Upload-Incomplete is not interoperable?

[guoye-zhang]

@martinthomson mentioned that Upload-Incomplete is not interoperable in the chat. Would you expand on your thoughts? Any suggestions on how we can improve it?

[martinthomson]

I'm not entirely sure what I was thinking at the time, but I can try to reconstruct it...

The goal of this design is to work seamlessly in those cases where resources don't support resumption of the upload. That is, you POST or PUT the data at the client, maybe putting in some headers to indicate that you want the special treatment. Then a server that supports resumption provides indications in the response, either using an informational response or just some extra header fields in a final response[^1].

Upload-Incomplete takes on three meanings in both cases. Absent could just mean that you don't support the spec, but maybe you have other signals, which might allow it to take on an implied false value. So:

• For a client request, a value of false is a little presumptive, because you can't guarantee that the entirety of the request will arrive and be processed. I don't see any interoperability risk here, but nor do I see any value in using this value under these conditions. This works pretty well as far as your design goes so far because this looks a lot like a legacy client.
• For a client request, a value of true is the most interesting. If I understand the intent, the goal is to have the client signal to the server that it doesn't intend to provide a complete upload with this request. This is where the interoperability risk arises. If the server doesn't understand the feature, then it might mistakenly believe that the upload is complete.
• For a server, as a response header field, I see no issue with any value this takes. However, it's probably worth enumerating the differences between the intended semantics of the field depending on role. For a server that responds true in response to a request with a false value, this could be very confusing. Generally speaking, I would expect that a server would not need to signal this in most cases as a final status code should be a better signal for the client that their request (complete or not) was received. Echoing a value of true might have some value in terms of indicating that the server received and understood that the request was an incomplete upload, but receipt should be implicit in a 2xx status code.

What I didn't see at the time of the comment was that you require that the server support the feature before using Upload-Incomplete. I don't think that suffices, but it might be enough to say that the client needs to know that the resource supports the feature. When you make that change, please make sure to link to the feature detection requirement in the definition of Upload-Incomplete; it's easy to miss otherwise.

[^1]: You probably want to use the 104 response from the server. You don't want to send a final response until you get all the content, though maybe a 202 is OK in this case if a client indicates that the upload is incomplete to begin with.

[guoye-zhang]

I agree that this is a bit confusing. Upload-Incomplete is a feature brought forward from tus-v1, and it's been used by clients to workaround upload size limits set by CDNs.

In tus-v2, we allow generic HTTP clients to do feature detection, but it's difficult for a generic client to make use of Upload-Incomplete, so it's left as an advanced feature for people who know their server supports it and needs it. It does make the protocol more complex, but we also want to avoid defining a protocol less capable than tus-v1.

[Acconut]

For a client request, a value of true is the most interesting. If I understand the intent, the goal is to have the client signal to the server that it doesn't intend to provide a complete upload with this request. This is where the interoperability risk arises. If the server doesn't understand the feature, then it might mistakenly believe that the upload is complete.

That is a very good point, yes! If we say, as you recommended, that this feature should only be used if support by the upload resource is known, and not automatically, this should all work out.

[Acconut]

I tried to clarify the requirement of server-side support in https://github.com/httpwg/http-extensions/commit/e388476cc6a16adfe1497c7d01fb012220f23733. Let me know if that is not sufficient.