File Operations

File Operations

Complete guide to uploading, downloading, and managing files in R2-Manager-Worker.

File Operations Overview

R2-Manager-Worker supports:

• 📤 Upload - Single or multiple files
• 📥 Download - Individual files or bulk ZIP archives
• 🔗 Share - Generate signed URLs for easy sharing
• ✏️ Rename - Rename files with validation via context menu
• 🔄 Move - Transfer files between buckets and to folders within buckets (v1.3.0)
• 📋 Copy - Duplicate files across buckets and to folders within buckets (v1.3.0)
• 🗑️ Delete - Remove single or multiple files
• 📁 Folder Navigation - Browse files within folders (see Folder Management)

Uploading Files

Via Web UI

Single File Upload:

1. Select a bucket from the sidebar
2. Click Upload File button
3. Choose a file from your computer
4. Upload begins automatically

Multiple File Upload:

1. Click Upload Multiple Files
2. Select multiple files at once
3. All files upload in parallel

Drag & Drop:

1. Drag files directly into the browser window
2. Files automatically upload to selected bucket

Upload Progress

• See real-time upload progress
• Pause individual uploads
• Resume interrupted uploads
• Cancel uploads at any time
• Integrity Verification - Automatic MD5 checksum verification
  • Visual feedback: "Verifying..." → "✓ Verified"
  • Ensures uploaded files match stored files exactly
  • Prevents data corruption and silent failures

File Size Limits

Application supports up to 500MB per file, but Cloudflare enforces plan-based limits:

Plan	Limit
Free/Pro	100MB
Business	200MB
Enterprise	500MB

Note: Upgrade your Cloudflare plan to increase limits.

Chunked Uploads

The application automatically splits large files:

• Chunk size: 10MB per chunk
• Auto-retry: Failed chunks retry automatically
• Resume: Can resume interrupted uploads
• Verification: Each chunk verified with MD5 checksum
• Transparent: You don't need to do anything!

Via API

curl -X POST https://YOUR_DOMAIN/api/files/my-bucket/upload \
  -H "X-File-Name: myfile.pdf" \
  -F "file=@myfile.pdf"

For chunked uploads:

curl -X POST https://YOUR_DOMAIN/api/files/my-bucket/upload \
  -H "X-File-Name: large-file.zip" \
  -H "X-Chunk-Index: 0" \
  -H "X-Total-Chunks: 5" \
  -F "file=@chunk-0.bin"

Downloading Files

Via Web UI

Single File Download:

1. Select a bucket
2. Find the file in the list
3. Click the Download icon
4. File saves to your Downloads folder

Multiple Files as ZIP:

1. Select multiple files (checkboxes)
2. Click Download as ZIP
3. All files packaged and downloaded

Download Speeds

Downloads use Cloudflare's edge network:

• Global CDN for fast delivery
• Automatic caching
• Optimized routing

Via API

Single File:

curl https://YOUR_DOMAIN/api/files/my-bucket/download/myfile.pdf \
  -o myfile.pdf

ZIP Archive:

curl -X POST https://YOUR_DOMAIN/api/files/my-bucket/download-zip \
  -H "Content-Type: application/json" \
  -d '{"files": ["file1.pdf", "file2.jpg"]}' \
  -o archive.zip

Sharing Files

Generate Signed URLs

Via Web UI (Grid View):

1. Hover over a file
2. Click the 🔗 Link icon in top-right corner
3. Signed URL copied to clipboard

Via Web UI (List View):

1. Find file in the list
2. Click Copy Link button
3. Share URL with anyone

How Signed URLs Work

Signed URLs include:

• HMAC-SHA256 signature for validation
• Timestamp for uniqueness
• File path in signature

Features:

• ✅ Anyone can download with the link (no login required)
• ✅ Links remain valid indefinitely
• ✅ Signature prevents tampering
• ✅ Each file gets unique signed URL

Share With Others

1. Generate a signed URL
2. Copy to clipboard (automatic)
3. Send via email, chat, or messaging app
4. Recipient clicks link to download

Via API

curl https://YOUR_DOMAIN/api/files/my-bucket/signed-url/myfile.pdf

Response:

{
  "success": true,
  "url": "https://your-domain.com/api/files/my-bucket/download/myfile.pdf?ts=123456&sig=abc123"
}

Renaming Files

Rename files within the same bucket while preserving location and integrity.

Via Web UI

1. Right-click on a file in grid or list view
2. Select ✏️ Rename from the context menu
3. Enter the new file name in the modal dialog
4. Press Enter or click Rename button
5. File is renamed instantly

Validation

The rename function validates file names to prevent issues:

• ✅ Cannot be empty
• ✅ Blocks invalid characters: < > : " | ? *
• ✅ Prevents Windows reserved names (CON, PRN, AUX, NUL, COM1-9, LPT1-9)
• ✅ Checks if file with new name already exists (prevents overwrites)

Features

• Path Preservation - File stays in the same folder
• Metadata Preserved - Content type and other metadata maintained
• Error Handling - Clear error messages for validation failures
• Keyboard Shortcuts:
  • Enter - Submit rename
  • Escape - Cancel rename
• Real-time Feedback - Instant validation as you type

Via API

curl -X PATCH https://YOUR_DOMAIN/api/files/my-bucket/old-name.pdf/rename \
  -H "Content-Type: application/json" \
  -d '{"newKey": "new-name.pdf"}'

Important Notes:

• Rename preserves the file's directory path
• Original file is deleted after successful rename
• Cannot rename to a name that already exists in the same location
• Operation cannot be undone

---

Moving Files

Move files between buckets or to folders within the same/different bucket (removes from source).

Via Web UI

1. Select one or more files
2. Click Transfer dropdown
3. Select Move to...
4. Choose destination bucket
5. NEW: Optionally enter a destination folder path (e.g., archives/2024)
6. Click Move Files

Files are removed from source location after successful move.

New Features (v1.3.0)

• ✅ Same-Bucket Moves - Move files to different folders within the same bucket
• ✅ Folder Targeting - Specify exact folder path for destination
• ✅ Path Input - Enter destination folder path like images/thumbnails or backups/daily
• ✅ Root Transfer - Leave path empty to move to bucket root

Examples

Move to different bucket's root:

• Source: bucket-a/report.pdf
• Destination bucket: bucket-b
• Destination path: (empty)
• Result: bucket-b/report.pdf

Move to folder in different bucket:

• Source: bucket-a/report.pdf
• Destination bucket: bucket-b
• Destination path: archives/2024
• Result: bucket-b/archives/2024/report.pdf

Move to folder in same bucket:

• Source: my-bucket/temp/document.pdf
• Destination bucket: my-bucket
• Destination path: processed
• Result: my-bucket/processed/document.pdf

Via API

Move to different bucket:

curl -X POST https://YOUR_DOMAIN/api/files/source-bucket/myfile.pdf/move \
  -H "Content-Type: application/json" \
  -d '{"destinationBucket": "dest-bucket"}'

Move to folder in different bucket:

curl -X POST https://YOUR_DOMAIN/api/files/source-bucket/myfile.pdf/move \
  -H "Content-Type: application/json" \
  -d '{
    "destinationBucket": "dest-bucket",
    "destinationPath": "archives/2024"
  }'

Move to folder in same bucket:

curl -X POST https://YOUR_DOMAIN/api/files/my-bucket/temp/file.pdf/move \
  -H "Content-Type: application/json" \
  -d '{
    "destinationBucket": "my-bucket",
    "destinationPath": "processed"
  }'

Copying Files

Copy files between buckets or to folders within the same/different bucket (keeps original).

Via Web UI

1. Select one or more files
2. Click Transfer dropdown
3. Select Copy to...
4. Choose destination bucket
5. NEW: Optionally enter a destination folder path (e.g., backups/monthly)
6. Click Copy Files

Original file remains in source location.

New Features (v1.3.0)

• ✅ Same-Bucket Copies - Create duplicates in different folders within same bucket
• ✅ Folder Targeting - Specify exact folder path for destination
• ✅ Path Input - Enter destination folder path like backups/weekly or archives/old
• ✅ Root Transfer - Leave path empty to copy to bucket root

Examples

Copy to different bucket's root:

• Source: bucket-a/data.csv
• Destination bucket: bucket-b
• Destination path: (empty)
• Result: bucket-b/data.csv (original remains)

Copy to folder in different bucket:

• Source: bucket-a/data.csv
• Destination bucket: bucket-b
• Destination path: backups/monthly
• Result: bucket-b/backups/monthly/data.csv (original remains)

Copy to folder in same bucket (create duplicate):

• Source: my-bucket/invoice.pdf
• Destination bucket: my-bucket
• Destination path: archive/2024
• Result: my-bucket/archive/2024/invoice.pdf (original remains at my-bucket/invoice.pdf)

Via API

Copy to different bucket:

curl -X POST https://YOUR_DOMAIN/api/files/source-bucket/myfile.pdf/copy \
  -H "Content-Type: application/json" \
  -d '{"destinationBucket": "dest-bucket"}'

Copy to folder in different bucket:

curl -X POST https://YOUR_DOMAIN/api/files/source-bucket/myfile.pdf/copy \
  -H "Content-Type: application/json" \
  -d '{
    "destinationBucket": "dest-bucket",
    "destinationPath": "backups/daily"
  }'

Copy to folder in same bucket:

curl -X POST https://YOUR_DOMAIN/api/files/my-bucket/report.pdf/copy \
  -H "Content-Type: application/json" \
  -d '{
    "destinationBucket": "my-bucket",
    "destinationPath": "archives/2024"
  }'

Deleting Files

Delete Single File

Via Web UI:

1. Right-click a file
2. Select Delete
3. Confirm deletion

Via API:

curl -X DELETE https://YOUR_DOMAIN/api/files/my-bucket/delete/myfile.pdf

Delete Multiple Files

Via Web UI:

1. Select multiple files (checkboxes)
2. Click Delete Selected
3. Confirm deletion

Via API:

# Delete files individually using the DELETE endpoint
curl -X DELETE https://YOUR_DOMAIN/api/files/my-bucket/delete/file1.pdf
curl -X DELETE https://YOUR_DOMAIN/api/files/my-bucket/delete/file2.jpg

Bulk Deletion

For large-scale deletions:

• Select all files: Click header checkbox
• Click Delete Selected
• Confirm deletion of all files

⚠️ Warning: Deletions are permanent and cannot be undone!

File Sorting & Filtering

Sort Options

Click the sort dropdown in the toolbar to choose:

• By Name - Alphabetically A-Z or Z-A
• By Size - Largest to smallest or smallest to largest
• By Type - Group by file extension
• By Date - Newest to oldest (default) or oldest to newest

Filter Files and Folders

NEW in v1.3.0: Advanced client-side filtering to quickly find files in large buckets.

Filter Bar Location:

• Positioned above the file action buttons
• Always visible for easy access
• Works in both grid and list views

How to Filter:

1. Text Search:

   • Type in the search box to filter by filename or folder name
   • Searches file/folder names only (not full paths)
   • Real-time filtering as you type
   • Case-insensitive matching
   • Partial matches supported (e.g., "report" finds "monthly-report.pdf", "Q4-Report.xlsx")

2. Type Filters:

   • All - Shows both files and folders (default)
   • Files Only - Shows only files, hides folders
   • Folders Only - Shows only folders, hides files

3. Clear Filter:

   • Click the ✕ button to clear the text filter
   • Reset type filter to "All" to show everything

Match Counter:

• Shows filtered results count (e.g., "23 of 156")
• Only appears when filter is active
• Updates in real-time as you type

Features:

• ✅ Real-time filtering - Results update instantly
• ✅ Case-insensitive - Matches regardless of capitalization
• ✅ Works with selections - Selected files remain selected
• ✅ Works with all views - Filter in grid or list view
• ✅ Mobile-friendly - Responsive layout on small screens

Examples:

Filter Text	Type Filter	Results
report	All	All files and folders with "report" in name
.pdf	Files Only	All PDF files
backup	Folders Only	All folders with "backup" in name
2024	All	Files and folders from 2024
invoice	Files Only	Files named "invoice-jan.pdf", "annual-invoice.xlsx", etc.

Use Cases:

• Quickly locate specific files in buckets with hundreds of items
• Find all files of a certain type (e.g., all PDFs)
• Locate folders for organization
• Filter before performing bulk operations (delete, move, copy)
• Search by date, project name, or any naming pattern

Pagination

Large buckets load efficiently:

• Up to 1000 items loaded per request
• Infinite scroll for seamless browsing
• Filter applies to all loaded items

File Details

View File Info

Click a file to see:

• File name
• File size (human-readable)
• Upload date/time
• Last modified date
• File type/MIME type

Copy File Details

• Click file name to copy to clipboard
• Click size to copy exact bytes
• Click date to copy ISO format

View Options

Grid View

• Visual preview (if available)
• Quick access to actions
• Better for browsing

Switch to Grid:

• Click Grid icon in toolbar

List View

• Detailed file information
• Sortable columns
• Better for large buckets

Switch to List:

• Click List icon in toolbar

Best Practices

Organizing Files

✅ DO:

• Use folder structure with prefixes: projects/2024/file.pdf
• Group related files: images/, documents/, videos/
• Use descriptive names: report-2024-q1.pdf

❌ DON'T:

• Upload all files to root: file1.pdf, file2.pdf
• Use unclear names: doc.pdf, IMG001.jpg
• Mix different file types randomly

Sharing Best Practices

✅ DO:

• Use signed URLs for secure sharing
• Set expiration reminders for temporary shares
• Document what each shared URL provides

❌ DON'T:

• Share bucket credentials
• Share direct API URLs with sensitive data
• Leave old signed URLs active indefinitely

Upload Best Practices

✅ DO:

• Check file size before uploading
• Upload during off-peak hours for large files
• Verify file integrity after upload

❌ DON'T:

• Interrupt uploads without reason
• Upload files larger than plan allows
• Upload sensitive unencrypted data

Troubleshooting

Upload Fails

Problem: Upload stops or fails

Solutions:

1. Check file size against plan limits
2. Verify internet connection
3. Try smaller files first
4. Check browser console for errors
5. Try a different browser

Download Takes Too Long

Problem: Download speed is slow

Solutions:

1. Try downloading during off-peak hours
2. Check your internet connection
3. Try downloading smaller files
4. Check if file is being accessed by others

Can't Find File After Upload

Problem: File uploaded but not visible

Solutions:

1. Refresh the page
2. Clear browser cache
3. Check if file was uploaded to correct bucket
4. Look for it in list view
5. Try searching by filename

Move/Copy Fails

Problem: Cannot move or copy file

Solutions:

1. Verify destination bucket exists
2. Check you have write permissions
3. Try copying to same bucket first
4. Check if file exists in source

API Reference

Complete endpoint documentation available in API Reference:

• List Files
• Upload File
• Download File
• Generate Signed URL
• Rename File
• Delete File
• Move File
• Copy File
• Download ZIP

---

Next Steps:

• Learn about Signed URLs & Sharing
• Explore the API Reference
• Check Troubleshooting for common issues