Transfer queue: bounded concurrency, pause/resume, retry, and throttling

[jhd3197]

The "transfer list" was, until now, exactly that — a list. Kick off ten downloads and all ten stampede the connection at once, with no way to pause one, no way to nudge another to the front, and a failed transfer just sat there red until you re-dragged the file. This PR turns that list into an actual queue with a scheduler behind it: a bounded number of transfers run at a time (default 3, adjustable 1–32) while the rest wait in a visible, reorderable FIFO. On top of the scheduler it adds per-transfer pause/resume, manual and automatic retry, and a global bandwidth throttle. The one design decision worth calling out: resuming a paused transfer re-runs its file from byte 0 rather than seeking — an honest choice that works identically across all eleven backends instead of depending on per-backend range support, and it lives in the shared copy loops so every backend gets the whole feature set for free.

Highlights

• Transfers now run a few at a time instead of all at once — the default is 3, configurable from 1 to 32, with everything else waiting in a queue that shows each row's position (#2 in queue).
• Pause and resume any transfer, individually or all at once from the panel header. A running transfer parks at the next chunk boundary; resuming it restarts that file cleanly.
• Transfers that fail on a transient network or timeout error retry themselves automatically with backoff, and any failed or canceled transfer gets a one-click Retry button.
• A global bandwidth limit (in KiB/s, 0 = unlimited) caps total throughput across all active transfers, adjustable live from the panel or from Settings.
• The queue panel gained per-row pause/resume/retry controls, up/down reorder arrows for waiting transfers, a pause-all toggle, and an inline throttle input.
• Concurrency and bandwidth defaults live under Settings → Transfers, persist across restarts, and apply live to in-flight transfers without a relaunch.

Technical changes

• TransferManager (transfer.rs) gained a real scheduler: a waiting VecDeque FIFO plus a tokio Semaphore for the concurrency bound. admit() pops a transfer only once it is at the FIFO front, the pause-all gate is open, and a permit is free — otherwise it waits as Queued and re-checks on a queue_gen watch channel.
• is_my_turn implements strict FIFO with one exception: per-transfer-paused rows are skipped so a paused transfer never head-of-line-blocks the rest of the queue; pause-all blocks everyone.
• PauseGate is a watch-channel gate used both for the manager-wide pause-all and for each transfer's own pause. checkpoint() is invoked in every backend copy loop — it first draws the chunk's bytes from the bandwidth bucket, then, if either gate is closed, parks until both reopen and returns a RestartFromPause marker error so the runner re-runs the file from byte 0.
• The two large inline per-backend match blocks in start_download/start_upload were extracted into shared run_download_task/run_upload_task runners plus dispatch_download/dispatch_upload. The runner loop handles both resume-from-pause restarts and auto-retry, and the same runners back Phase 3 manual retry.
• Auto-retry: transient failures (Network/Timeout, classified via classify_message, now pub(crate)) retry up to twice with 5s then 20s backoff; a retry_attempt field plus a "retrying in Ns (attempt N/3)" error string drive the panel's mid-retry rendering. The concurrency permit is deliberately held through the backoff sleep so a retrying transfer keeps its slot.
• TokenBucket (Phase 4) is one global token bucket (AtomicU64 rate, tokio Instant timestamps) shared by every copy loop, so the cap is split across active transfers rather than applied per transfer. It draws in tranches capped at one second of rate (min 64 KiB) so a large chunk is charged in full while a 1 KiB file never waits a whole window, and each internal sleep is capped at 250ms so a live rate change takes effect promptly.
• Manual retry re-enqueues under the same transfer id using the original, already-policy-resolved source/destination captured in RetryInfo (so the panel row resets in place). set_concurrency grows by adding permits immediately and shrinks by forgetting permits as running transfers release them, so in-flight transfers are never killed to satisfy a lowered bound.
• New Tauri commands — transfer_pause, transfer_resume, transfer_retry, transfer_move, transfer_pause_all, transfer_resume_all, transfer_set_concurrency, transfer_set_throttle, transfer_queue_state — registered in lib.rs. cancel now takes the AppHandle, removes the id from the waiting queue, and emits transfer://updated (there is no dedicated cancel event).
• lib.rs setup applies the persisted transferConcurrency/transferThrottleKbps settings to the manager at startup so the queue starts from the user's saved values.
• Frontend IPC (ipc.ts): the new transfer://queue event and transfer_queue_state snapshot are wired via onTransferQueue and a typed TransferQueueState; onTransferEvent learned the updated kind. transfersStore now tracks queue/pausedAll/concurrency/throttleKbps, treats updated like progress (replaces the row, never toasts), and clearFinished keeps paused rows since they are still in flight.
• TransferQueue.tsx: per-row pause/resume/retry buttons, ↑/↓ reorder arrows for waiting rows, queue-position labels, a pause-all header toggle, and a ThrottleInput that commits on blur or Enter; rows mid-auto-retry render their status text in the warning color instead of danger.
• notifications.ts: the batch tracker clears canceled rows from the active set on updated (canceled emits no terminal event, so without this the batch would never flush) while leaving paused rows in flight.
• Settings.tsx gained "Concurrent transfers" (1–32) and "Bandwidth limit" (KiB/s) fields under Transfers; settingsStore persists both and live-applies each change through the matching ipc setter.

[Copilot]

Pull request overview

This PR turns Faro’s transfer “list” into a real, user-controllable transfer queue spanning both the Rust backend scheduler and the React/Zustand UI, adding bounded concurrency, pause/resume, retry, and a global bandwidth throttle.

Changes:

• Backend: add FIFO + semaphore scheduler, pause gates, auto/manual retry, and token-bucket throttling, with new Tauri commands/events.
• Frontend: wire new transfer queue IPC/events into Zustand stores and update the transfer panel UI (pause/resume/retry/reorder/throttle + settings).
• Add mock + headless verification script to exercise the transfer queue UI without the Rust backend.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
src/stores/transfersStore.ts	Track queue state in the store and wire new transfer queue listeners + commands.
src/stores/settingsStore.ts	Persist and live-apply transfer concurrency and throttle settings.
src/mock/transfers.ts	Mock transfer-queue engine for headless UI verification.
src/mock/demo.ts	Expose transfer mock seeding/call inspection via window.__demo.
src/mock/core.ts	Route new transfer-queue IPC commands to the mock engine.
src/lib/types.ts	Add paused status, retryAttempt, and TransferQueueState type.
src/lib/notifications.ts	Treat updated events to avoid wedged batch notifications on cancel.
src/lib/ipc.ts	Add new transfer queue IPC commands and transfer://queue listener.
src/components/TransferQueue.tsx	UI controls for pause/resume/retry/reorder + throttle input + queue position labels.
src/components/Settings.tsx	Settings UI for concurrent transfers + bandwidth limit.
src-tauri/src/virtualfs/mod.rs	Treat Paused as “still in progress” for hydration waits.
src-tauri/src/transfer.rs	Implement scheduler, pause gates, retry/backoff, and global throttling + tests.
src-tauri/src/lib.rs	Apply persisted transfer queue settings at startup and register new commands.
src-tauri/src/foldersync.rs	Treat Paused transfers as still pending in sync waits.
src-tauri/src/error.rs	Make classify_message usable for transfer retry classification.
src-tauri/src/commands.rs	Add new Tauri commands for transfer queue controls and queue snapshot.
src-tauri/Cargo.toml	Add tokio test-util for paused-clock tests.
scripts/verify-transfers.mjs	Headless mock UI verification script for transfer queue behavior.
docs/plans/ROADMAP.md	Mark Plan 17 as built and document remaining smoke run step.

Suppressed comments (2)

src-tauri/src/transfer.rs:2635

• Same issue as run_download_task: after admission, the queue isn’t bumped until completion, so subsequent queued uploads may never re-check their turn and concurrency > 1 won’t actually take effect.

    let Some(_permit) = mgr.admit(&id).await else {
        return;
    };
    let mut auto_retries = 0u32;

src-tauri/src/commands.rs:838

• Same as concurrency: the throttle is live-applied but this command doesn’t emit transfer://queue, so the frontend store’s throttleKbps can remain stale (especially noticeable when adjusting from Settings or in another window).

/// Live-adjust the global bandwidth cap in KiB/s (0 = unlimited). Takes
/// effect on the next chunk of every active transfer (Plan 17 Phase 4).
#[tauri::command]
pub async fn transfer_set_throttle(
    kbps: u64,
    state: State<'_, AppState>,
) -> Result<(), String> {
    state.transfers.set_throttle_kbps(kbps);
    Ok(())

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.