From 0ce0571a707988463f434293c012219e6f41fe16 Mon Sep 17 00:00:00 2001 From: Michael Stingl Date: Tue, 5 Dec 2023 14:16:52 +0100 Subject: [PATCH 1/3] [docs-only] Explain tus upload metadata for client implementations --- docs/apis/http/tus_upload.md | 57 ++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/docs/apis/http/tus_upload.md b/docs/apis/http/tus_upload.md index 62a415de35..a1a73631e6 100644 --- a/docs/apis/http/tus_upload.md +++ b/docs/apis/http/tus_upload.md @@ -13,6 +13,35 @@ In situations where file uploads might be interrupted due to network issues, bro 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](https://tus.io/protocols/resumable-upload) for more details. +## Supported tus Features + +The backend announces certain tus features to clients. WebDAV responses come with tus HTTP headers for the offical tus features, and additional, ownCloud specific features are announced via the capabilities endpoint (e.g. `https://localhost:9200/ocs/v1.php/cloud/capabilities?format=json`). + +```json +{ + "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": "" + } + } + } + } + } + } +} +``` + +| Parameter | Environment Variable | Default Value | Description | +| -------------- | ------------------------------ | ------------- | ------------------------------------------------------------------- | +| max_chunk_size | FRONTEND_UPLOAD_MAX_CHUNK_SIZE | 10000000 | Announces the max chunk sizes in bytes for uploads via the clients. | + ## Upload in Chunks ### Create an Upload URL @@ -191,3 +220,31 @@ curl -ks -XPOST https://ocis.test/remote.php/dav/spaces/{space-id} \ {{< hint type=warning title="Important Warning" >}} `Upload-Length` header should contain the exact byte as upload content. {{< /hint >}} + +## Supported Upload-Metadata + +Upload-metadata key-value pairs aren't specified in the general tus docs. The following ones are supported in the ownCloud ecosystem: + +| Parameter (key) | Example (value, MUST be Base64 encoded) | Description | +| ---------------------- | -----------------------------------------------------------------------------------------------------------------------------------------------------| ------------- | ------------------------- | +| filename (mandatory) | example.pdf | Filename | +| mtime (recommended) | 1701708712 | Modification time (Unix time format) | +| checksum (recommended) | SHA1 a330de5886e5a92d78fb3f8d59fe469857759e72 | Checksum, computed from the client | +| name | example.pdf | Alternate name sent by the web UI | +| type | application/pdf | MIME Type, sent by the web UI | +| filetype | application/pdf | MIME Type, sent by the web UI | +| relativePath | undefined | Sent by the web UI | +| spaceId | 8748cddf-66b7-4b85-91a7-e6d08d8e1639$a9778d63-21e7-4d92-9b47-1b81144b9993 | Sent by the web UI | +| spaceName | Personal | Sent by the web UI | +| driveAlias | personal/admin | Sent by the web UI | +| driveType | personal | Sent by the web UI | +| currentFolder | / | Sent by the web UI | +| currentFolderId | ODc0OGNkZGYtNjZiNy00Yjg1LTkxYTctZTZkMDhkOGUxNjM5JGE5Nzc4ZDYzLTIxZTctNGQ5Mi05YjQ3LTFiODExNDRiOTk5MyFhOTc3OGQ2My0yMWU3LTRkOTItOWI0Ny0xYjgxMTQ0Yjk5OTM= | Sent by the web UI | +| uppyId | uppy-example/pdf-1e-application/pdf-238300 | Sent by the web UI | +| relativeFolder | | Key sent by the web UI, but without value | +| tusEndpoint | https://ocis.ocis-traefik.latest.owncloud.works/remote.php/dav/spaces/8748cddf-66b7-4b85-91a7-e6d08d8e1639$a9778d63-21e7-4d92-9b47-1b81144b9993 | Sent by the web UI | +| uploadId | 71d5f878-a96c-4d7b-9627-658d782c93d7 | Sent by the web UI | +| topLevelFolderId | undefined | Sent by the web UI | +| routeName | files-spaces-generic | Sent by the web UI | +| routeDriveAliasAndItem | cGVyc29uYWwvYWRtaW4= | Sent by the web UI | +| routeShareId | | Key sent by the web UI, but without value | From 5e21dc57f2dd53422e29f790679e6e39e7f6150e Mon Sep 17 00:00:00 2001 From: Michael Stingl <214010+michaelstingl@users.noreply.github.com> Date: Thu, 7 Dec 2023 13:15:04 +0100 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Jannik Stehle <50302941+JammingBen@users.noreply.github.com> --- docs/apis/http/tus_upload.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/apis/http/tus_upload.md b/docs/apis/http/tus_upload.md index a1a73631e6..1a1b2ae3d8 100644 --- a/docs/apis/http/tus_upload.md +++ b/docs/apis/http/tus_upload.md @@ -233,7 +233,7 @@ Upload-metadata key-value pairs aren't specified in the general tus docs. The fo | name | example.pdf | Alternate name sent by the web UI | | type | application/pdf | MIME Type, sent by the web UI | | filetype | application/pdf | MIME Type, sent by the web UI | -| relativePath | undefined | Sent by the web UI | +| relativePath | undefined | File path relative to the folder that is being uploaded, including the filename. Sent by the web UI | | spaceId | 8748cddf-66b7-4b85-91a7-e6d08d8e1639$a9778d63-21e7-4d92-9b47-1b81144b9993 | Sent by the web UI | | spaceName | Personal | Sent by the web UI | | driveAlias | personal/admin | Sent by the web UI | @@ -241,10 +241,10 @@ Upload-metadata key-value pairs aren't specified in the general tus docs. The fo | currentFolder | / | Sent by the web UI | | currentFolderId | ODc0OGNkZGYtNjZiNy00Yjg1LTkxYTctZTZkMDhkOGUxNjM5JGE5Nzc4ZDYzLTIxZTctNGQ5Mi05YjQ3LTFiODExNDRiOTk5MyFhOTc3OGQ2My0yMWU3LTRkOTItOWI0Ny0xYjgxMTQ0Yjk5OTM= | Sent by the web UI | | uppyId | uppy-example/pdf-1e-application/pdf-238300 | Sent by the web UI | -| relativeFolder | | Key sent by the web UI, but without value | +| relativeFolder | | File path relative to the folder that is being uploaded, without filename. Sent by the web UI | | tusEndpoint | https://ocis.ocis-traefik.latest.owncloud.works/remote.php/dav/spaces/8748cddf-66b7-4b85-91a7-e6d08d8e1639$a9778d63-21e7-4d92-9b47-1b81144b9993 | Sent by the web UI | | uploadId | 71d5f878-a96c-4d7b-9627-658d782c93d7 | Sent by the web UI | | topLevelFolderId | undefined | Sent by the web UI | | routeName | files-spaces-generic | Sent by the web UI | | routeDriveAliasAndItem | cGVyc29uYWwvYWRtaW4= | Sent by the web UI | -| routeShareId | | Key sent by the web UI, but without value | +| routeShareId | | Share ID when uploading into a received folder share. Sent by the web UI | From 56422ceaaf4529321d959ef361994939072b2dd0 Mon Sep 17 00:00:00 2001 From: Michael Stingl Date: Wed, 13 Dec 2023 14:34:54 +0100 Subject: [PATCH 3/3] Document name/filename and type/filetype as alias --- docs/apis/http/tus_upload.md | 44 +++++++++++++++++------------------- 1 file changed, 21 insertions(+), 23 deletions(-) diff --git a/docs/apis/http/tus_upload.md b/docs/apis/http/tus_upload.md index 1a1b2ae3d8..7eb33a0336 100644 --- a/docs/apis/http/tus_upload.md +++ b/docs/apis/http/tus_upload.md @@ -225,26 +225,24 @@ curl -ks -XPOST https://ocis.test/remote.php/dav/spaces/{space-id} \ Upload-metadata key-value pairs aren't specified in the general tus docs. The following ones are supported in the ownCloud ecosystem: -| Parameter (key) | Example (value, MUST be Base64 encoded) | Description | -| ---------------------- | -----------------------------------------------------------------------------------------------------------------------------------------------------| ------------- | ------------------------- | -| filename (mandatory) | example.pdf | Filename | -| mtime (recommended) | 1701708712 | Modification time (Unix time format) | -| checksum (recommended) | SHA1 a330de5886e5a92d78fb3f8d59fe469857759e72 | Checksum, computed from the client | -| name | example.pdf | Alternate name sent by the web UI | -| type | application/pdf | MIME Type, sent by the web UI | -| filetype | application/pdf | MIME Type, sent by the web UI | -| relativePath | undefined | File path relative to the folder that is being uploaded, including the filename. Sent by the web UI | -| spaceId | 8748cddf-66b7-4b85-91a7-e6d08d8e1639$a9778d63-21e7-4d92-9b47-1b81144b9993 | Sent by the web UI | -| spaceName | Personal | Sent by the web UI | -| driveAlias | personal/admin | Sent by the web UI | -| driveType | personal | Sent by the web UI | -| currentFolder | / | Sent by the web UI | -| currentFolderId | ODc0OGNkZGYtNjZiNy00Yjg1LTkxYTctZTZkMDhkOGUxNjM5JGE5Nzc4ZDYzLTIxZTctNGQ5Mi05YjQ3LTFiODExNDRiOTk5MyFhOTc3OGQ2My0yMWU3LTRkOTItOWI0Ny0xYjgxMTQ0Yjk5OTM= | Sent by the web UI | -| uppyId | uppy-example/pdf-1e-application/pdf-238300 | Sent by the web UI | -| relativeFolder | | File path relative to the folder that is being uploaded, without filename. Sent by the web UI | -| tusEndpoint | https://ocis.ocis-traefik.latest.owncloud.works/remote.php/dav/spaces/8748cddf-66b7-4b85-91a7-e6d08d8e1639$a9778d63-21e7-4d92-9b47-1b81144b9993 | Sent by the web UI | -| uploadId | 71d5f878-a96c-4d7b-9627-658d782c93d7 | Sent by the web UI | -| topLevelFolderId | undefined | Sent by the web UI | -| routeName | files-spaces-generic | Sent by the web UI | -| routeDriveAliasAndItem | cGVyc29uYWwvYWRtaW4= | Sent by the web UI | -| routeShareId | | Share ID when uploading into a received folder share. Sent by the web UI | +| Parameter (key) | Example (value, MUST be Base64 encoded) | Description | +| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | +| `name` OR `filename` (mandatory) | example.pdf | Filename | +| `mtime` (recommended) | 1701708712 | Modification time (Unix time format) | +| `checksum` (recommended) | SHA1 a330de5886e5a92d78fb3f8d59fe469857759e72 | Checksum, computed from the client | +| `type` OR `filetype` | application/pdf | MIME Type, sent by the web UI | +| `relativePath` | undefined | File path relative to the folder that is being uploaded, including the filename. Sent by the web UI | +| `spaceId` | 8748cddf-66b7-4b85-91a7-e6d08d8e1639$a9778d63-21e7-4d92-9b47-1b81144b9993 | Sent by the web UI | +| `spaceName` | Personal | Sent by the web UI | +| `driveAlias` | personal/admin | Sent by the web UI | +| `driveType` | personal | Sent by the web UI | +| `currentFolder` | / | Sent by the web UI | +| `currentFolderId` | 8748cddf-66b7-4b85-91a7-e6d08d8e1639$a9778d63-21e7-4d92-9b47-1b81144b9993!a9778d63-21e7-4d92-9b47-1b81144b9993 | Sent by the web UI | +| `uppyId` | uppy-example/pdf-1e-application/pdf-238300 | Sent by the web UI | +| `relativeFolder` | | File path relative to the folder that is being uploaded, without filename. Sent by the web UI. | +| `tusEndpoint` | https://ocis.ocis-traefik.latest.owncloud.works/remote.php/dav/spaces/8748cddf-66b7-4b85-91a7-e6d08d8e1639$a9778d63-21e7-4d92-9b47-1b81144b9993 | Sent by the web UI | +| `uploadId` | 71d5f878-a96c-4d7b-9627-658d782c93d7 | Sent by the web UI | +| `topLevelFolderId` | undefined | Sent by the web UI | +| `routeName` | files-spaces-generic | Sent by the web UI | +| `routeDriveAliasAndItem` | cGVyc29uYWwvYWRtaW4= | Sent by the web UI | +| `routeShareId` | | Share ID when uploading into a received folder share. Sent by the web UI |