Folder Management

Folder Management

Comprehensive guide to managing folders in R2 buckets.

Overview

R2-Manager-Worker provides full folder management capabilities built on top of R2's flat object storage structure. Folders are represented by object key prefixes with / delimiters, similar to how AWS S3 handles folders.

Key Features:

• 📁 Create folders with placeholder .keep files
• ✏️ Rename folders (batch copy + delete operations)
• 📋 Copy folders between buckets and to folders within buckets (v1.3.0)
• 🔄 Move folders between buckets and to folders within buckets (v1.3.0)
• 🗑️ Delete folders and all contents
• 🧭 Breadcrumb navigation for folder hierarchy
• 👁️ Visual folder display with distinct icons

---

How Folders Work in R2

Virtual Folders

R2 uses a flat object storage model (like AWS S3). Folders don't exist as separate entities - they're created by using / characters in object keys:

my-bucket/
  ├── images/photo1.jpg      (key: "images/photo1.jpg")
  ├── images/photo2.jpg      (key: "images/photo2.jpg")
  └── documents/report.pdf   (key: "documents/report.pdf")

Folder Detection

The Worker uses R2's delimiter parameter to detect folders:

// List request with delimiter=/
const response = await bucket.list({
  delimiter: "/",
  prefix: "images/",
});

// Returns:
// - objects: Files directly in the prefix
// - delimitedPrefixes: Folder paths (e.g., ["images/subfolder/"])

Empty Folders

When you create a folder, the application creates a .keep placeholder file:

my-folder/
  └── .keep  (0 bytes)

This ensures the folder exists even when empty. The .keep file is automatically created and can be safely deleted once other files are added.

---

Creating Folders

Via UI

1. Navigate to a bucket
2. Click 📁 Create Folder button
3. Enter folder name
4. Click Create Folder

Folder Name Rules:

• Letters (a-z, A-Z), numbers (0-9), hyphens (-), underscores (_), forward slashes (/)
• Cannot start or end with /
• Cannot contain consecutive slashes (//)
• Use / for nested folders (e.g., parent/child/grandchild)

Via API

POST /api/folders/:bucketName/create
Content-Type: application/json

{
  "folderName": "my-folder"
}

Example with nested folders:

{
  "folderName": "documents/2025/reports"
}

Response:

{
  "success": true,
  "folderPath": "documents/2025/reports/"
}

---

Navigating Folders

Breadcrumb Navigation

The UI provides breadcrumb navigation showing your current location:

🏠 Root › documents › 2025 › reports

• Click any breadcrumb to navigate to that level
• Click 🏠 Root to return to bucket root
• Current location is highlighted and non-clickable

Folder Display

Folders appear above files in the grid view:

📁 documents/        Folder
📁 images/          Folder
📄 readme.txt       2.5 KB    Mar 1, 2025
📄 config.json      1.2 KB    Feb 28, 2025

• Click a folder to navigate into it
• Folders show "Folder" instead of file size
• Distinct folder icon (📁) vs file icons

---

Renaming Folders

Rename a folder by updating all object keys with the folder prefix.

Via Web UI

1. Right-click on a folder in grid or list view
2. Select ✏️ Rename from the context menu
3. Enter the new folder name in the modal dialog
4. Press Enter or click Rename button
5. Folder and all contents are renamed

Validation:

• Cannot be empty
• Only letters, numbers, hyphens, underscores, and forward slashes allowed
• Cannot start or end with /
• Cannot contain consecutive slashes (//)
• Checks if folder with new name already exists

Features:

• Keyboard Shortcuts:
  • Enter - Submit rename
  • Escape - Cancel rename
• Real-time Feedback - Instant validation as you type
• Progress Tracking - See how many files are being renamed

Via API

PATCH /api/folders/:bucketName/rename
Content-Type: application/json

{
  "oldPath": "old-folder",
  "newPath": "new-folder"
}

Response:

{
  "success": true,
  "copied": 45,
  "failed": 0
}

Process:

1. Lists all objects with oldPath prefix
2. Copies each object to newPath prefix
3. Deletes original objects
4. Processes in batches of 100 with 300ms delays

Important Notes:

• All nested folders and files are renamed
• Metadata is preserved during copy
• Large folders may take time to rename
• Operation cannot be undone

---

Copying Folders

Copy a folder and all its contents to another bucket or to a folder within the same/different bucket (v1.3.0).

Via Web UI

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

Source folder remains unchanged.

New Features (v1.3.0)

• ✅ Same-Bucket Copies - Create folder duplicates within the same bucket
• ✅ Folder Targeting - Copy to specific folder locations
• ✅ Path Input - Enter destination folder path like archives/backups
• ✅ Root Transfer - Leave path empty to copy to bucket root

Via API

POST /api/folders/:sourceBucket/:folderPath/copy
Content-Type: application/json

{
  "destinationBucket": "target-bucket",
  "destinationPath": "optional/destination/folder"
}

URL Parameters:

• :sourceBucket - Source bucket name
• :folderPath - Folder path to copy (URL-encoded)

Request Body:

• destinationBucket (required) - Target bucket name
• destinationPath (optional) - Destination folder path
  • Leave empty to copy to bucket root with source folder name
  • Specify path to copy folder to specific location

Response:

{
  "success": true,
  "copied": 120,
  "failed": 2
}

Examples:

# Copy 'images' folder to different bucket (preserves folder name)
POST /api/folders/bucket-a/images/copy
{"destinationBucket": "bucket-b"}
# Result: bucket-b/images/... (all contents copied)

# Copy 'images' folder to specific location in different bucket
POST /api/folders/bucket-a/images/copy
{"destinationBucket": "bucket-b", "destinationPath": "backups/2024/images"}
# Result: bucket-b/backups/2024/images/...

# Copy folder to another folder within same bucket
POST /api/folders/my-bucket/reports/copy
{"destinationBucket": "my-bucket", "destinationPath": "archives/reports"}
# Result: my-bucket/archives/reports/... (duplicate created)

Process:

1. Lists all objects with folder prefix in source bucket
2. For each object:
   • Fetches from source
   • Uploads to destination with new path
3. Source folder remains unchanged
4. Processes in batches with rate limiting

Important Notes:

• Same-bucket copies are allowed when destinationPath differs from source
• Allows creating folder duplicates within a bucket at different paths
• Source folder structure is preserved in destination

---

Moving Folders

Move a folder and all its contents to another bucket or to a folder within the same/different bucket (v1.3.0).

Via Web UI

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

Source folder is removed after successful move.

New Features (v1.3.0)

• ✅ Same-Bucket Moves - Reorganize folders within the same bucket
• ✅ Folder Targeting - Move to specific folder locations
• ✅ Path Input - Enter destination folder path like processed/incoming
• ✅ Root Transfer - Leave path empty to move to bucket root

Via API

POST /api/folders/:sourceBucket/:folderPath/move
Content-Type: application/json

{
  "destinationBucket": "target-bucket",
  "destinationPath": "optional/destination/folder"
}

URL Parameters:

• :sourceBucket - Source bucket name
• :folderPath - Folder path to move (URL-encoded)

Request Body:

• destinationBucket (required) - Target bucket name
• destinationPath (optional) - Destination folder path
  • Leave empty to move to bucket root with source folder name
  • Specify path to move folder to specific location

Response:

{
  "success": true,
  "moved": 85,
  "failed": 1
}

Examples:

# Move 'temp' folder to different bucket
POST /api/folders/bucket-a/temp/move
{"destinationBucket": "bucket-b"}
# Result: bucket-b/temp/... (bucket-a/temp/ is deleted)

# Move 'drafts' folder to specific location in different bucket
POST /api/folders/bucket-a/drafts/move
{"destinationBucket": "bucket-b", "destinationPath": "archives/2024/drafts"}
# Result: bucket-b/archives/2024/drafts/... (bucket-a/drafts/ is deleted)

# Move folder to another folder within same bucket
POST /api/folders/my-bucket/incoming/move
{"destinationBucket": "my-bucket", "destinationPath": "processed/incoming"}
# Result: my-bucket/processed/incoming/... (my-bucket/incoming/ is deleted)

Process:

1. Copies all objects to destination (same as copy operation)
2. Deletes all objects from source folder
3. Source folder is removed after successful move

Important Notes:

• Same-bucket moves are allowed when destinationPath differs from source
• Allows reorganizing folders within a bucket
• This is a copy + delete operation
• If copy succeeds but delete fails, you may have duplicates
• Cannot be undone
• Large folders may take significant time

---

Deleting Folders

Delete a folder and optionally all its contents.

Via UI

1. Navigate to parent folder
2. Select the folder (checkbox or click)
3. Click Delete Selected
4. Confirm deletion

Via API

Check folder contents (safe mode):

DELETE /api/folders/:bucketName/:folderPath

Force delete (delete all contents):

DELETE /api/folders/:bucketName/:folderPath?force=true

Response without force (folder contains files):

{
  "success": false,
  "fileCount": 45,
  "message": "Folder contains files. Use force=true to delete."
}

Response with force:

{
  "success": true,
  "deleted": 45
}

Process:

1. Lists all objects with folder prefix
2. Counts total files
3. If force=false and files exist, returns file count
4. If force=true, deletes all objects in batches
5. Rate limiting applied (300ms between batches)

Safety Features:

• Two-step confirmation in UI
• Requires explicit force=true for non-empty folders
• Reports number of files that will be deleted

---

Batch Operations

All folder operations process objects in batches to avoid rate limits:

Batch Size: 100 objects per request
Rate Limiting: 300-500ms delay between batches
Progress Tracking: Returns success/failure counts

Performance Considerations

Small folders (<100 files): < 1 second
Medium folders (100-500 files): 1-5 seconds
Large folders (500-1000 files): 5-15 seconds
Very large folders (>1000 files): May take several minutes

Tips for large folders:

• Operations run in the background
• Progress is reported via response
• Monitor Worker logs for detailed progress
• Consider chunking very large moves/copies

---

Folder Validation

Naming Rules

Valid Characters:

• Letters: a-z, A-Z
• Numbers: 0-9
• Special: - (hyphen), _ (underscore), / (forward slash)

Invalid Patterns:

• Leading slash: /folder
• Trailing slash: folder/ (automatically added)
• Consecutive slashes: folder//subfolder
• Empty names

Valid Examples:

images
documents/2025
my-folder_v2
reports/Q1/final-draft

Invalid Examples:

/images              (leading slash)
my folder            (space not allowed)
docs//2025           (consecutive slashes)
files\reports        (backslash not allowed)

Frontend Validation

The UI validates folder names in real-time:

• ✅ Green checkmark for valid names
• ❌ Red error message for invalid names
• Automatic .keep file creation
• Path normalization

---

Best Practices

Organization

1. Use descriptive names: user-uploads not temp
2. Consistent naming: Use hyphens or underscores, not both
3. Date-based folders: 2025/01 for time-series data
4. Hierarchical structure: projects/client-name/documents

Performance

1. Avoid deep nesting: Keep folder depth under 5 levels
2. Batch similar operations: Move/copy multiple folders together
3. Monitor large operations: Check Worker logs for progress
4. Use meaningful prefixes: Helps with listing and filtering

Maintenance

1. Clean up empty folders: Delete unnecessary .keep files
2. Consolidate folders: Merge related folders periodically
3. Document structure: Maintain a folder structure guide
4. Regular audits: Review and reorganize folder hierarchy

---

Troubleshooting

Folder Not Appearing

Cause: No objects with that prefix
Solution: Create a file or .keep placeholder in the folder

Rename/Move Taking Too Long

Cause: Large number of objects
Solution:

• Wait for operation to complete
• Check Worker logs for progress
• Consider breaking into smaller operations

Delete Fails with "Folder Not Empty"

Cause: force=true not set
Solution: Add ?force=true query parameter

Objects Not Copying

Cause: Rate limiting or API errors
Solution:

• Check Worker logs for specific errors
• Retry operation
• Verify source bucket permissions

Folder Name Validation Errors

Cause: Invalid characters or patterns
Solution:

• Use only letters, numbers, hyphens, underscores, slashes
• Remove leading/trailing slashes
• Fix consecutive slashes

---

API Error Codes

Status Code	Description
200 OK	Operation succeeded
400 Bad Request	Invalid folder name or parameters
404 Not Found	Bucket or folder not found
500 Internal Server Error	Operation failed (check logs)

---

Additional Resources

• API Reference - Complete endpoint documentation
• File Operations - Managing individual files
• Bucket Management - Working with buckets
• Cloudflare R2 Object Keys - Understanding R2's flat structure

---

📝 Note: Folder operations are batch processes that may take time for large folders. Always monitor operation results and check logs for detailed progress information.