Skip to main content

Resumable Upload

OpenCloud supports the tus resumable-upload protocol, which is a robust, modular, and open protocol designed to resume large file uploads reliably over HTTP. In situations where file uploads might be interrupted due to network issues, browser crashes, or other unforeseen interruptions, tus ensures that uploads can be resumed from the point of failure without losing data. This documentation shows some basic examples, refer tus official site for more details.

Supported tus Features​

The backend announces certain tus features to clients. WebDAV responses come with tus HTTP headers for the official tus features, and additional, OpenCloud specific features are announced via the capabilities endpoint (e.g. https://localhost:9200/ocs/v1.php/cloud/capabilities?format=json).

The following snippet shows the relevant part of the server capabilities of OpenCloud that concerns the tus upload:

{
  "ocs": {
    "data": {
      "capabilities": {
        "files": {
          "tus_support": {
            "version": "1.0.0",
            "resumable": "1.0.0",
            "extension": "creation,creation-with-upload",
            "max_chunk_size": 10000000,
            "http_method_override": ""
          }
        }
      }
    }
  }
}
ParameterEnvironment VariableDefault ValueDescription
max_chunk_sizeFRONTEND_UPLOAD_MAX_CHUNK_SIZE10000000Announces the max chunk sizes in bytes for uploads via the clients.

Upload in Chunks​

Create an Upload URL​

The client must send a POST request against a known upload creation URL to request a new upload resource. The filename has to be provided in base64-encoded format.

Example:

# base64 encoded filename 'tustest.txt' is 'dHVzdGVzdC50eHQ='
echo -n 'tustest.txt' | base64
curl -ks -XPOST https://cloud.opencloud.test/remote.php/dav/spaces/8d72036d-14a5-490f-889e-414064156402$196ac304-7b88-44ce-a4db-c4becef0d2e0 \
-H "Authorization: Bearer eyJhbGciOiJQUzI..."\
-H "Tus-Resumable: 1.0.0" \
-H "Upload-Length: 10" \
-H "Upload-Metadata: filename dHVzdGVzdC50eHQ="

The server will return a temporary upload URL in the location header of the response:

< Location: https://cloud.opencloud.test/data/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJyZXZhIiwiZXhwIjoxNjk3NTMyNTc5LCJpYXQiOjE2OTc0NDYxNzksInRhcmdldCI6Imh0dHA6Ly9sb2NhbGhvc3Q6OTE1OC9kYXRhL3R1cy8zYTU3ZWZlMS04MzE0LTQ4MGEtOWY5Ny04N2Q1YzBjYTJhMTgifQ.FbrlY7mdOfsbFgMrP8OtcHlCEq72a2ZVnPD2iBo9MfM

Upload the First Chunk​

Once a temporary upload URL has been created, a client can send a PATCH request to upload a file. The file content should be sent in the body of the request:

curl -ks -XPATCH https://temporary-upload-url \
-H "Authorization: Bearer eyJhbGciOiJQUzI..." \
-H "Tus-Resumable: 1.0.0" \
-H "Upload-Offset: 0" \
-H "Content-Type: application/offset+octet-stream" -d "01234"

Upload Further Chunks​

After the first chunk is uploaded, the second chunk can be uploaded by pointing Upload-Offset to exact position that was returned in the first response. Upload process will not be marked as complete until the total uploaded content size matches the Upload-Length specified during the creation of the temporary URL.

curl -ks -XPATCH https://temporary-upload-url \
-H "Authorization: Bearer eyJhbGciOiJQUzI..." \
-H "Tus-Resumable: 1.0.0" \
-H "Upload-Offset: 5" \
-H "Content-Type: application/offset+octet-stream" -d "56789"
Important Warning

Upload-Offset header indicates the byte position in the target file where the server should start writing the upload content. It ensures data integrity and order during the upload process.

Creation with Upload​

curl -ks -XPOST https://cloud.opencloud.test/remote.php/dav/spaces/\{space-id\} \
-H "Authorization: Bearer eyJhbGciOiJQUzI..." \
-H "Tus-Resumable: 1.0.0" \
-H "Upload-Length: 14" \
-H "Content-Type: application/offset+octet-stream" \
-H "Upload-Metadata: filename dGVzdC50eHQ=" \
-H "Tus-Extension: creation-with-upload" \
-d "upload content"
Important Warning

The Upload-Length header of the request has to contain the exact size of the upload content in byte.

Supported Upload-Metadata​

Upload-metadata key-value pairs aren't specified in the general tus docs. The following ones are supported in the OpenCloud ecosystem:

Parameter (key)Example (value, MUST be Base64 encoded)Description
name OR filename (mandatory)example.pdfFilename
mtime (recommended)1701708712Modification time (Unix time format)
checksum (recommended)SHA1 a330de5886e5a92d78fb3f8d59fe469857759e72Checksum, computed from the client
type OR filetypeapplication/pdfMIME Type, sent by the web UI
relativePathundefinedFile path relative to the folder that is being uploaded, including the filename. Sent by the web UI
spaceId8748cddf-66b7-4b85-91a7-e6d08d8e1639$a9778d63-21e7-4d92-9b47-1b81144b9993Sent by the web UI
spaceNamePersonalSent by the web UI
driveAliaspersonal/adminSent by the web UI
driveTypepersonalSent by the web UI
currentFolder/Sent by the web UI
currentFolderId8748cddf-66b7-4b85-91a7-e6d08d8e1639$a9778d63-21e7-4d92-9b47-1b81144b9993!a9778d63-21e7-4d92-9b47-1b81144b9993Sent by the web UI
uppyIduppy-example/pdf-1e-application/pdf-238300Sent by the web UI
relativeFolderFile path relative to the folder that is being uploaded, without filename. Sent by the web UI.
tusEndpointhttps://cloud.opencloud.test/remote.php/dav/spaces/8748cddf-66b7-4b85-91a7-e6d08d8e1639$a9778d63-21e7-4d92-9b47-1b81144b9993Sent by the web UI
uploadId71d5f878-a96c-4d7b-9627-658d782c93d7Sent by the web UI
topLevelFolderIdundefinedSent by the web UI
routeNamefiles-spaces-genericSent by the web UI
routeDriveAliasAndItemcGVyc29uYWwvYWRtaW4=Sent by the web UI
routeShareIdShare ID when uploading into a received folder share. Sent by the web UI