# 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](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

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

For chunked uploads:

```bash
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:**

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

**ZIP Archive:**

```bash
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

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

**Response:**

```json
{
  "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

```bash
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:**

```bash
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:**

```bash
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:**

```bash
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:**

```bash
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:**

```bash
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:**

```bash
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:**

```bash
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:**

```bash
# 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](API-Reference#file-management):

- [List Files](API-Reference#list-files)
- [Upload File](API-Reference#upload-file)
- [Download File](API-Reference#download-file)
- [Generate Signed URL](API-Reference#generate-signed-url)
- [Rename File](API-Reference#rename-file)
- [Delete File](API-Reference#delete-file)
- [Move File](API-Reference#move-file)
- [Copy File](API-Reference#copy-file)
- [Download ZIP](API-Reference#download-zip-archive)

---

**Next Steps:**

- Learn about [Signed URLs & Sharing](Signed-URLs-&-Sharing)
- Explore the [API Reference](API-Reference)
- Check [Troubleshooting](Troubleshooting) for common issues