# Rclone usage guide (Stratofusion defaults)

This project standardizes when to use `copy` vs `copyto` and applies safe, performant defaults.

## API Documentation

The rclone service provides interactive API documentation via Swagger UI:

- **Local Development**: http://localhost:3001/docs.
- **Production VM**: https://rclone.stratofusion.io/docs when operator access and service policy permit it.
- **Legacy Fly.io recovery**: the development and production Fly endpoints are intentionally stopped; do not probe them during normal operation.
- **OpenAPI Spec**: http://localhost:3001/openapi.json.

The Swagger UI provides:
- Complete API endpoint documentation.
- Request/response schemas.
- Interactive API testing.
- Example requests and responses.

## TL;DR
- Single file → `copyto` (we default to `--no-traverse`).
- Whole folder (recursive) → `copy` (we default to `--fast-list`).
- We always include metadata preservation and progress/stats unless overridden by options.

## When to use which
- `copy` copies directory contents recursively. Ideal for folder→folder.
- `copyto` accepts an explicit destination path/filename. Ideal for single file copies and renames.

Both share the same flag families (filters, progress, checks, etc.).

## Project defaults (implemented in the rclone service)
- Single-file copy API (/api/copy and batch-copy items).
  - command: `copyto`.
  - defaults: `--no-traverse` to avoid listing the destination for one-off files.
- Folder copy API (/api/copy-folder).
  - command: `copy`.
  - defaults: `--fast-list` to reduce API round trips on deep trees.
- Progress/metadata.
  - `--progress` when requested; otherwise `--stats 1s --stats-one-line`.
  - `--metadata` preserved by default (note: some providers limit folder mtime support).

## Practical CLI examples

Single file (explicit filename):

```bash
rclone copyto sourceRemote:/path/file.pdf destRemote:/dest/dir/file.pdf --no-traverse --metadata --progress
```

Folder to folder (recursive):

```bash
rclone copy sourceRemote:/path/to/folder destRemote:/path/to/folder --fast-list --metadata --progress
```

Batch of files (each item gets an explicit dest):

```bash
# Pseudocode style: each file uses copyto + --no-traverse
for f in files; do
  rclone copyto src:"$f" dst:"$dest_dir/$(basename "$f")" --no-traverse --metadata
done
```

## Notes
- Cross-provider transfers (e.g., Drive→Dropbox) stream through the client; server-side copies across configs are generally not possible.
- `--checksum` can be more accurate but slower and not supported by all remotes; default size+modtime is typically sufficient.
- The app exposes an advanced `Use checksum verification when supported` toggle for copy, move, backup, and sync launches. When enabled, the rclone service appends `--checksum` and lets rclone use hashes where the remotes expose compatible checksums.
- Sync launches show a dedicated safety panel explaining force resync, checksum comparison, same-path conflict policy, first-time two-way merge behavior, managed recovery attempts, and protected rclone flags. Normal supported syncs use `--fast-list` so deep folder trees are listed with fewer API round trips before transfer progress begins; first-time and recovery two-way resyncs disable `--fast-list` so metadata scans can emit incremental progress. Two-way conflict policy maps to rclone `--conflict-resolve` and first-time `--resync-mode`; destination-only files still merge back during rclone `--resync`, so users who do not want that should choose one-way sync or an empty destination. Google Drive <-> OneDrive syncs recursively exclude StratoFusion duplicate-marker quarantine folders, and Google Drive to non-Google bisync skips native Google Workspace documents so virtual 0-byte Docs do not block reverse-copy initialization. Force-sync safety bypasses and arbitrary custom flags remain hidden until they can be allowlisted and confirmed safely.
- Avoid redundant flags; our server avoids adding duplicates where practical.

## Partial failure behavior
- rclone exit code `1` usually means the copy partially succeeded but one or more files failed.
- We now preserve backend error details through SSE so the UI can show the specific failing item (for example, `unicode-file.xml`) instead of a generic `Transfer failed` message.
- For large folder copies, review the final error text and operation ID to identify and retry only the failed files.
- For Google Workspace accounts, virtual container IDs like `root` are now treated as My Drive (not `team_drive`) to avoid `Shared drive not found: root` failures.
- For OneDrive-to-OneDrive folder copy, we apply `--ignore-existing` by default to reduce `nameAlreadyExists` failures from files still being uploaded/finalized.
- For OneDrive-to-OneDrive folder copy, we also apply conservative retry/throttle tuning (`--retries 8`, `--low-level-retries 20`, `--retries-sleep 5s`, `--transfers 2`, `--checkers 4`, `--tpslimit 8`) to reduce transient Graph API 500 processing failures.
- When OneDrive-to-OneDrive folder copy finishes with exactly one failed file, the service now auto-attempts a fallback single-file retry using `copyto` with `--disable Copy` and without `--metadata` before returning a final failed status.
- For OneDrive remotes, virtual IDs such as `root` are filtered from `drive_id` config so rclone uses the actual drive root (prevents `ObjectHandle is Invalid` on source/destination init).

## Where this is wired in code
- Single-file copy defaults: `fly-rclone/src/routes/copyRoutes.js` and `/api/batch-copy` in `fly-rclone/server.js`.
- Folder copy defaults: `/api/copy-folder` in `fly-rclone/server.js`.

If you need to override defaults (e.g., disable fast-list for a specific backend quirk), extend the API `options` handling to toggle these flags.