[whatwg/fetch] Resumable File Uploads (Issue #1626)

Inside IETF's HTTP working group, we are currently discussing a draft for resumable file uploads over HTTP: https://datatracker.ietf.org/doc/draft-ietf-httpbis-resumable-upload/01/. The draft itself is rather new and might undergo severe changes, but I would like to bring this draft to the WHATWG for two reasons:

1) Ask you as experienced HTTP users for general feedback on the draft and its approach to resumable uploads, and
2) discuss a possible inclusion of resumable file uploads in the Fetch API.

In the remaining text here, I would like to briefly outline the current draft (version -01) and provide an initial idea how it could interact with the Fetch API:

## Resumable Uploads over HTTP

Traditional file uploads using POST or PUT requests are not resumable, i.e. if the connection is interrupted during the upload, the entire upload has to be retried and some data might have to be retransmitted. For larger files or users with poor connectivity, this can be problematic. Many applications have solved this by implementing a proprietary solution for providing resumability. With our draft, we try to standardize an approach to resumable uploads, so that compatible software implementations are possible. Maybe resumable uploads capabilities can be implemented directly into browsers and other platforms directly.

The draft has been designed that it builds upon "traditional" file uploads and allows extending them with resumablity capabilities if supported by the client and server. If a client wants to upload a file using a POST request, the client can indicate its interest in resumablity by including a special header in the request (currently, this is the `Upload-Incomplete` header, but this name might change and is not too relevant for the broader picture here).

If the server also supports resumability, it can respond with an informational `104 Upload Resumption Supported` response. It includes a `Location` header, which points to a newly created upload resource. This resource can be used to resume the upload, if it gets interrupted.

The request we are currently talking about is the normal POST/PUT request whose body is the file that should be uploaded. So while the file is being transferred the server might send this informational response.

If this request succeeds and the upload is finished successful, the upload resource is never used and everything is fine.

If the request gets interrupted or the connectivity is lost, the upload is interrupted and can be resumed using the upload resource. For this, the client first sends a `HEAD` request to the upload resource to fetch the offset (i.e. the number of bytes that the server successfully received and stored). After this, the client can upload the remaining data after the offset using a `PATCH` request to the upload resource. This dance is repeated until the entire file has been transferred without the need of retransmitting any chunks.

## Interaction with Fetch API

As mentioned before, this draft attempts to extend traditional file uploads with resumability. If a server does not support resumability, the file upload should just be treated as any other HTTP request.

If the developer wants to upload a file resumably, it could indicate this interest to the server using an option `resumable`:

```js
  const response = await fetch(url, {
    method: "POST"
    body: file,
    resumable: true,
  });
```

When this option is set, the client should into the special header and monitor the connection for the `104 Upload Resumption Supported` informational response. Based on whether the client received it, multiple outcomes are possible:

- the request completes -> the response is provided as for any normal fetch invocation
- the request is interrupted and no `104 Upload Resumption Supported` was received -> an error is raised as for any normal fetch invocation
- the request is interrupted and a `104 Upload Resumption Supported` was received -> the client initiates a resumption and either raises an error or provides a response depending on the outcome

This way, resumable file uploads are provided by the Fetch API and can easily be used by developers without the inclusion of an additional library.

I hope this provides a quick overview of our current approach to resumable uploads. We are interested in any feedback on the approach itself, but also if there is interest in integrating it into Fetch.

-- 
Reply to this email directly or view it on GitHub:
https://github.com/whatwg/fetch/issues/1626
You are receiving this because you are subscribed to this thread.

Message ID: <whatwg/fetch/issues/1626@github.com>