File Upload

This document describes the file upload process in Cloudreve. The upload flow varies depending on the storage policy type, but generally follows a three-step process.

Overview

A complete file upload consists of three steps:

1. Create upload session - Request an upload session from Cloudreve server
2. Upload chunks - Upload file data in chunks to the storage provider
3. Complete upload - Finalize the upload (for some storage policies)

For small files, consider using the Update file content API for a simpler single-request upload.

Step 1: Create Upload Session

Use the Create upload session API to initiate an upload. The response includes:

• session_id - Unique identifier for this upload session
• chunk_size - Size of each chunk in bytes
• upload_urls - Pre-signed URLs for uploading chunks (varies by storage policy)
• credential - Authentication credential for chunk uploads
• expires - Session expiration timestamp
• storage_policy - Storage policy configuration including:
  • policy_type - Type of storage provider
  • chunk_concurrency - Maximum concurrent chunk uploads allowed
  • streaming_encryption - Whether streaming encryption is supported
• encrypt_metadata - Encryption parameters (if client-side encryption is enabled)

Step 2: Upload Chunks

The chunk upload method depends on the storage policy type:

Local / Remote Storage Policy

For local storage, or any storage policy with storage_policy.relay set to true, use the Upload file chunk API.

For remote (slave node) storage, send chunks to the URL in upload_urls (single element). The request format is similar to the local chunk upload, with these differences:

• Chunk index is passed via query parameter chunk, e.g., http://slave.example.com/api/v4/slave/upload/{session_id}?chunk=2
• Authorization header uses the credential value from the upload session, e.g., Bearer Cr sBnnQ3rZ-UBr7d8ohKpUFtsQc8OMLuWwn1VhuJtdc5k=:1749623351

S3-Compatible Storage Policies

For S3, OSS, COS, OBS, and KS3 storage policies, use the pre-signed URLs in upload_urls (one URL per chunk). Refer to the respective cloud provider's multipart upload documentation:

• S3: UploadPart
• OSS: UploadPart
• COS: UploadPart
• OBS: Uploading Parts
• KS3: Uses the same API as S3

OneDrive

For OneDrive storage policy, use the upload URL from upload_urls with byte range headers. Refer to Microsoft's Upload bytes to the upload session documentation.

Qiniu

For Qiniu storage policy, refer to Upload Part documentation.

Upyun

For Upyun storage policy, refer to Large File Upload documentation.

Step 3: Complete Upload

The completion step varies by storage policy:

Storage Policy	Completion Method
Local / Remote / Upyun	Automatic - no action required after last chunk
OneDrive	Complete OneDrive upload
S3 / KS3	CompleteMultipartUpload, then Complete S3 upload callback
OSS	CompleteMultipartUpload (callback handled automatically)
COS	Complete Multipart Upload, then Complete COS upload callback
OBS	Completing a Multipart Upload, then Complete OBS upload callback
Qiniu	Complete Multipart Upload

Chunked Upload

Files are split into chunks based on the chunk_size returned by the upload session. The chunk_concurrency field in the storage policy specifies how many chunks can be uploaded simultaneously.

Client-Side Encryption

When file encryption is enabled on the server, the upload session response includes encrypt_metadata containing:

• cipher - Encryption algorithm (e.g., aes-256-ctr)
• key_plain_text - Base64-encoded encryption key
• iv - Base64-encoded initialization vector

The client should encrypt file data using AES-256-CTR mode before uploading. With streaming encryption, chunk boundaries don't need to align with AES block boundaries - calculate the correct counter offset for each chunk based on its byte position in the file.

Reference Implementation

For a complete implementation reference, see:

• Web: frontend/src/component/Uploader/core/uploader
• Desktop: desktop/crates/cloudreve-sync/src/uploader