Clarifications on what it means for an upload to be "finished"

[nh2]

I have a couple questions regarding the concept of uploads finishing in the spec (https://tus.io/protocols/resumable-upload.html).

• The Expiration and Termination extensions talk about "finished" and "unfinished" uploads, but it is neither defined what that means nor stated that these terms are explicitly undefined and it is communicated out-of-band whether an upload is finished. The only cases where a concept of "finished" is easily available are:

  • In the Concatenation extension, where one could easily argue that the "final" upload makes that upload "finished".
  • If the Creation extension is used and either Upload-Length was set at the beginning, or Upload-Defer-Length was used and with a subsequent

    Once it is known the Client MUST set the Upload-Length header in the next PATCH request.
    the length was learned, and that offset eventually reached.

  But these are extensions; likely other independent extensions shouldn't depend on them for semantics.

• The Core protocol has only 1 ocurrence of the Upload-Length header, namely in the response to the HEAD request:

  If the size of the upload is known, the Server MUST include the Upload-Length header in the response.

Thus, it would be great to have the following clarifications stated somewhere explicit in the FAQ:

• The Core protocol does not define a notion of when an upload is finished. At any given time it is unknown whether more data will be added to an Upload.

• In the Creation extension, regarding

  Once it is known the Client MUST set the Upload-Length header in the next PATCH request.

  there is the case that a client sent a previous PATCH request, and then later learns that there is no more data. In this case, I suppose the client would send a PATCH request with an empty body and sets the Upload-Length header for it (this is what e.g. the tus.py client does, see Setting of Upload-Length with empty PATCH request? cenkalti/tus.py#8).
  If this is how it's supposed to work, might be nice to state that in the FAQ, because implementing a server I wasn't at first sure what to do with empty PATCH requests.

I believe the following is a bit unclear in the spec:

• In the Concatenation extension:

  The Upload-Length header MUST be included if the length of the final resource can be calculated at the time of the request.

  • Included in what, the final POST requests that set Upload-Concat: partial? Or also the PATCH request, that transmit the data (similar to "set the Upload-Length header in the next PATCH request" from the Creation extension)? If the latter, it's confusing that this wording doesn't use "in the next PATCH request; the current wording implies that if if the client knows the length all the way from the beginning to the end, the Upload-Length header MUST be included in each of the request (but the subsequent "Example" doesn't show that happening).
    It seems beneficial to me to word that logic exactly like in the Creation extension.

Thanks for considering / answering those points!

[Acconut]

Hello and thanks for these questions!

The Core protocol does not define a notion of when an upload is finished. At any given time it is unknown whether more data will be added to an Upload.

An upload is considered finished if and only if its Upload-Length matches Upload-Offset and the upload length is not deferred. If this connection is not met, the upload is unfinished / incomplete. An upload that is created through the Concatenation extension is immediately finished once the POST request is successfully responded to, meaning such an upload cannot be modified a posteriori.

there is the case that a client sent a previous PATCH request, and then later learns that there is no more data. In this case, I suppose the client would send a PATCH request with an empty body and sets the Upload-Length header for it

Yes, that is correct. An empty PATCH request shall be used in this case.

In the Concatenation extension:
> The Upload-Length header MUST be included if the length of the final resource can be calculated at the time of the request.

I am a bit confused about your question here. The cited statement refers to situations when the Upload-Length header must be included in responses, not requests. Your question reads to me as if you think it refers to requests. Is that the case?

I hope my response is still helpful to you!

[nh2]

An upload is considered finished if and only if its Upload-Length matches Upload-Offset and the upload length is not deferred.

OK, that makes sense. I think it would be great to state explicitly in the Spec or FAQ.

The cited statement refers to situations when the Upload-Length header must be included in responses, not requests.
Your question reads to me as if you think it refers to requests. Is that the case?

Ah, yes.

The other statements immediately before all started with "The response to a HEAD request" or "The Server MUST respond with". I understood the absence of those such that "The Upload-Length header MUST be included" thus to mean it would apply to both servers and clients.

Also, the sentence ends with "at the time of the request".

I think it would be clearer to say "at the time of the response" or "at the time the request is handled", given that it is talking about the server.

---

My questions are answered, thanks! Please feel free to close the issue unless you want to use it for tracking any FAQ updates / wording clarifications, in case you decide to make any.