Speed up downloads by combining multiple network connections in parallel
TypeScript bandwidth-aggregationcross-platformdesktop-appdownloaderdownloadmanagerlinuxmacosmulticonnectionparallel-downloadswindows
fix: persist downloads across relaunches
HiteshRohirae56fbcf3738e
diff --git a/README.md b/README.mdindex cc6bbe4..ccd7d43 100644--- a/README.md+++ b/README.md@@ -52,6 +52,7 @@ File ──→ Split ─────┼── Ethernet (IP: 10.0.0.12) ───- 🔌 **Hardware interface detection** — queries macOS hardware ports via `networksetup` so Wi-Fi, Ethernet, tethered iPhones, and Thunderbolt bridges are labeled by real device names instead of bare BSD names (`en0`, `en6`).- ⚖️ **Dynamic work-stealing queue** — chunks are leased from a shared pending queue; faster networks pull more chunks instead of waiting for slower connections to finish.- ⏸️ **Resumable downloads** — pausing cleanly aborts in-flight socket connections while preserving downloaded `part-N` chunk files on disk.+- 💾 **Relaunch recovery** — interrupted downloads are restored as paused after Plexo restarts, with progress and part files preserved in application data.- 🛡️ **Safe, integrity-checked resume** — re-verifies remote `ETag` and `Last-Modified` validators before resuming, refusing to resume (rather than corrupting the file) if the server-side file has changed.- 🔁 **Automatic retry with backoff** — failed chunks are automatically returned to the queue and retried with exponential backoff (up to 5 retries, 1s–15s backoff).- 💤 **Stall detection** — automatically drops and re-queues connections that remain open but silent (>20s without incoming data).@@ -157,6 +158,10 @@ When you resume:2. **Safe resume**: If the validators match, Plexo checks which `part-N` files are already complete on disk, skips them, and queues only the remaining chunks.3. **Guard against corruption**: If the file on the server has changed, Plexo refuses to resume to prevent combining incompatible slices into a corrupt file.+Download manifests and partial data are stored under Plexo's application-data directory. If Plexo+quits or crashes during a transfer, it restores that transfer as paused on the next launch. Explicitly+cancelling or removing a download still deletes its partial data.+---# What is a chunk?diff --git a/src/main/download/downloadManager.ts b/src/main/download/downloadManager.tsindex 23f9083..ce2641c 100644--- a/src/main/download/downloadManager.ts+++ b/src/main/download/downloadManager.ts@@ -1,6 +1,16 @@import { randomUUID } from 'node:crypto'import { createReadStream, createWriteStream } from 'node:fs'-import { mkdir, rm, stat, statfs, truncate } from 'node:fs/promises'+import {+ mkdir,+ readFile,+ readdir,+ rename,+ rm,+ stat,+ statfs,+ truncate,+ writeFile+} from 'node:fs/promises'import { basename, join } from 'node:path'import type { BrowserWindow } from 'electron'import { app } from 'electron'@@ -37,6 +47,17 @@ interface DownloadRuntime {pushScheduled: booleanblocks: BlockState[]totalBlocks: number+ persistenceTimer?: NodeJS.Timeout+ persistenceChain: Promise<void>+ removed: boolean+}++interface PersistedDownload {+ version: 1+ savedAt: number+ state: DownloadState+ requestPayload: StartDownloadRequest+ activeInterfaces: NetworkInterfaceInfo[]}const PROGRESS_THROTTLE_MS = 200@@ -191,13 +212,99 @@ function appendFileToStream(sourcePath: string, output: NodeJS.WritableStream):export class DownloadManager {private runtimes = new Map<string, DownloadRuntime>()+ private readonly initialization: Promise<void>constructor(private getWindow: () => BrowserWindow | null,- private getInterfaceById: (id: string) => NetworkInterfaceInfo | undefined- ) {}+ private getInterfaceById: (id: string) => NetworkInterfaceInfo | undefined,+ private refreshInterfaces: () => Promise<NetworkInterfaceInfo[]>+ ) {+ this.initialization = this.restorePersistedDownloads()+ }++ private downloadsRoot(): string {+ return join(app.getPath('userData'), 'downloads')+ }++ private downloadDir(id: string): string {+ return join(this.downloadsRoot(), id)+ }++ private manifestPath(id: string): string {+ return join(this.downloadDir(id), 'manifest.json')+ }++ private async restorePersistedDownloads(): Promise<void> {+ let entries: string[]+ try {+ entries = await readdir(this.downloadsRoot())+ } catch {+ return+ }++ await Promise.all(+ entries.map(async (id) => {+ try {+ const persisted = JSON.parse(+ await readFile(this.manifestPath(id), 'utf-8')+ ) as PersistedDownload+ if (persisted.version !== 1 || persisted.state.id !== id || !persisted.state.blocks)+ return++ const state = persisted.state+ const blocks = state.blocks+ if (!blocks) return+ if (state.status === 'downloading') {+ state.status = 'paused'+ state.pausedAt = persisted.savedAt || Date.now()+ }+ state.speedBytesPerSec = 0+ for (const chunk of state.chunks) {+ chunk.speedBytesPerSec = 0+ if (+ chunk.status === 'downloading' ||+ chunk.status === 'retrying' ||+ chunk.status === 'pending'+ ) {+ chunk.status = 'paused'+ }+ }+ for (const block of blocks) {+ if (block.status === 'downloading') block.status = 'pending'+ }++ const runtime: DownloadRuntime = {+ state,+ requestPayload: persisted.requestPayload,+ activeInterfaces: persisted.activeInterfaces,+ chunkRuntimes: new Map(),+ tempDir: join(this.downloadDir(id), 'parts'),+ speedSamplesByChunk: new Map(),+ pushScheduled: false,+ blocks,+ totalBlocks: state.totalBlocks ?? blocks.length,+ persistenceChain: Promise.resolve(),+ removed: false+ }+ this.runtimes.set(id, runtime)+ await this.persistNow(runtime)+ } catch {+ // Ignore incomplete or corrupt manifests; other downloads can still be restored.+ }+ })+ )+ }++ async getCurrentDownload(): Promise<DownloadState | null> {+ await this.initialization+ const latest = [...this.runtimes.values()].sort(+ (a, b) => b.state.startedAt - a.state.startedAt+ )[0]+ return latest ? structuredClone(latest.state) : null+ }async start(requestPayload: StartDownloadRequest): Promise<string> {+ await this.initializationconst interfaces = requestPayload.interfaceIds.map((interfaceId) => this.getInterfaceById(interfaceId)).filter((iface): iface is NetworkInterfaceInfo => Boolean(iface))@@ -209,7 +316,7 @@ export class DownloadManager {await ensureDiskSpace(requestPayload.destinationDir, requestPayload.totalBytes)const id = randomUUID()- const tempDir = join(app.getPath('temp'), 'plexo', id)+ const tempDir = join(this.downloadDir(id), 'parts')await mkdir(tempDir, { recursive: true })// Claimed on disk, not just picked, so a second download of the same file@@ -337,9 +444,12 @@ export class DownloadManager {speedSamplesByChunk: new Map(),pushScheduled: false,blocks,- totalBlocks: blocks.length+ totalBlocks: blocks.length,+ persistenceChain: Promise.resolve(),+ removed: false}this.runtimes.set(id, runtime)+ await this.persistNow(runtime)this.pushUpdate(runtime)void this.runChunksToCompletion(runtime, runtime.state.chunks)@@ -347,7 +457,7 @@ export class DownloadManager {return id}- pause(id: string): void {+ async pause(id: string): Promise<void> {const runtime = this.runtimes.get(id)if (!runtime || runtime.state.status !== 'downloading') return@@ -369,6 +479,7 @@ export class DownloadManager {chunkRuntime.controller.abort()}this.pushUpdate(runtime)+ await this.persistNow(runtime)}resume(id: string): void {@@ -394,11 +505,42 @@ export class DownloadManager {runtime.state.error ='The remote file changed while this download was paused, so resuming would corrupt it. Start the download over instead.'this.pushUpdate(runtime)+ await this.cleanupTempDir(runtime)await this.discardUnfinishedDestination(runtime)return}+ let availableInterfaces: NetworkInterfaceInfo[]+ try {+ availableInterfaces = await this.refreshInterfaces()+ } catch {+ runtime.state.error = 'Could not refresh network interfaces. Try resuming again.'+ this.pushUpdate(runtime)+ return+ }+ if (runtime.state.status !== 'paused') return++ const selectedIds = new Set(runtime.requestPayload.interfaceIds)+ runtime.activeInterfaces = availableInterfaces.filter((iface) => selectedIds.has(iface.id))+ if (runtime.activeInterfaces.length === 0) {+ runtime.state.error =+ 'None of the networks selected for this download are currently available. Reconnect one and try again.'+ this.pushUpdate(runtime)+ return+ }++ for (let index = 0; index < runtime.state.chunks.length; index++) {+ const chunk = runtime.state.chunks[index]+ const iface =+ runtime.activeInterfaces.find((entry) => entry.id === chunk.interfaceId) ??+ runtime.activeInterfaces[index % runtime.activeInterfaces.length]+ chunk.interfaceId = iface.id+ chunk.interfaceLabel = iface.displayName+ chunk.interfaceKind = iface.kind+ }+runtime.state.status = 'downloading'+ runtime.state.error = undefinedif (runtime.state.pausedAt) {runtime.state.totalPausedMs =(runtime.state.totalPausedMs || 0) + (Date.now() - runtime.state.pausedAt)@@ -436,9 +578,10 @@ export class DownloadManager {for (const chunkRuntime of runtime.chunkRuntimes.values()) {chunkRuntime.controller.abort()}- this.pushUpdate(runtime)+ this.pushUpdate(runtime, false)void this.cleanupTempDir(runtime)void this.discardUnfinishedDestination(runtime)+ void this.removePersistedDownload(runtime)}remove(id: string): void {@@ -447,12 +590,17 @@ export class DownloadManager {this.cancel(id)}this.runtimes.delete(id)+ if (runtime) void this.removePersistedDownload(runtime)}- cancelAll(): void {- for (const id of this.runtimes.keys()) {- this.cancel(id)- }+ async suspendAll(): Promise<void> {+ await this.initialization+ await Promise.all(+ [...this.runtimes.values()].map(async (runtime) => {+ if (runtime.state.status === 'downloading') await this.pause(runtime.state.id)+ else await this.persistNow(runtime)+ })+ )}/** Runs (or resumes) fixed worker streams in parallel, leasing blocks until all are completed. */@@ -694,7 +842,8 @@ export class DownloadManager {}, PROGRESS_THROTTLE_MS)}- private pushUpdate(runtime: DownloadRuntime): void {+ private pushUpdate(runtime: DownloadRuntime, persist = true): void {+ if (persist) this.schedulePersistence(runtime)const window = this.getWindow()if (!window || window.isDestroyed()) returnif (runtime.state.status === 'paused' || runtime.state.status === 'cancelled') {@@ -793,4 +942,50 @@ export class DownloadManager {// Best-effort cleanup — a leftover temp dir isn't worth surfacing an error for.}}++ private schedulePersistence(runtime: DownloadRuntime): void {+ if (runtime.removed || runtime.persistenceTimer) return+ runtime.persistenceTimer = setTimeout(() => {+ runtime.persistenceTimer = undefined+ void this.persistNow(runtime)+ }, PROGRESS_THROTTLE_MS)+ }++ private persistNow(runtime: DownloadRuntime): Promise<void> {+ if (runtime.removed) return runtime.persistenceChain+ if (runtime.persistenceTimer) {+ clearTimeout(runtime.persistenceTimer)+ runtime.persistenceTimer = undefined+ }++ runtime.persistenceChain = runtime.persistenceChain+ .catch(() => {})+ .then(async () => {+ if (runtime.removed) return+ const dir = this.downloadDir(runtime.state.id)+ const path = this.manifestPath(runtime.state.id)+ const temporaryPath = `${path}.tmp`+ const persisted: PersistedDownload = {+ version: 1,+ savedAt: Date.now(),+ state: structuredClone(runtime.state),+ requestPayload: runtime.requestPayload,+ activeInterfaces: runtime.activeInterfaces+ }+ await mkdir(dir, { recursive: true })+ await writeFile(temporaryPath, JSON.stringify(persisted), 'utf-8')+ await rename(temporaryPath, path)+ })+ .catch(() => {+ // Progress persistence is best-effort; transfer errors are surfaced separately.+ })+ return runtime.persistenceChain+ }++ private async removePersistedDownload(runtime: DownloadRuntime): Promise<void> {+ runtime.removed = true+ if (runtime.persistenceTimer) clearTimeout(runtime.persistenceTimer)+ await runtime.persistenceChain.catch(() => {})+ await rm(this.downloadDir(runtime.state.id), { recursive: true, force: true })+ }}diff --git a/src/main/index.ts b/src/main/index.tsindex 750b6e0..1dcb858 100644--- a/src/main/index.ts+++ b/src/main/index.ts@@ -7,6 +7,7 @@ import type { DownloadManager } from './download/downloadManager'let mainWindow: BrowserWindow | null = nulllet downloadManager: DownloadManager | null = null+let quitAfterSuspending = falsefunction createWindow(): void {mainWindow = new BrowserWindow({@@ -73,8 +74,14 @@ app.whenReady().then(() => {})})-app.on('before-quit', () => {- downloadManager?.cancelAll()+app.on('before-quit', (event) => {+ if (quitAfterSuspending || !downloadManager) return++ event.preventDefault()+ void downloadManager.suspendAll().finally(() => {+ quitAfterSuspending = true+ app.quit()+ })})app.on('window-all-closed', () => {diff --git a/src/main/ipc/handlers.ts b/src/main/ipc/handlers.tsindex 1da6394..e2d06c7 100644--- a/src/main/ipc/handlers.ts+++ b/src/main/ipc/handlers.ts@@ -17,14 +17,18 @@ const NETWORK_SETTINGS_URL = 'x-apple.systempreferences:com.apple.preference.netexport function registerIpcHandlers(getWindow: () => BrowserWindow | null): DownloadManager {let cachedInterfaces: NetworkInterfaceInfo[] = []- const manager = new DownloadManager(getWindow, (id) =>- cachedInterfaces.find((iface) => iface.id === id)- )-- ipcMain.handle(IpcChannels.listInterfaces, async () => {+ const refreshInterfaces = async (): Promise<NetworkInterfaceInfo[]> => {cachedInterfaces = await listActiveInterfaces()return cachedInterfaces- })+ }++ const manager = new DownloadManager(+ getWindow,+ (id) => cachedInterfaces.find((iface) => iface.id === id),+ refreshInterfaces+ )++ ipcMain.handle(IpcChannels.listInterfaces, refreshInterfaces)ipcMain.handle(IpcChannels.pingInterfaces, async () => measureLatencies(cachedInterfaces))@@ -67,8 +71,10 @@ export function registerIpcHandlers(getWindow: () => BrowserWindow | null): Downmanager.start(request))+ ipcMain.handle(IpcChannels.getCurrentDownload, async () => manager.getCurrentDownload())+ipcMain.handle(IpcChannels.pauseDownload, async (_event, id: string) => {- manager.pause(id)+ await manager.pause(id)})ipcMain.handle(IpcChannels.resumeDownload, async (_event, id: string) => {diff --git a/src/preload/index.ts b/src/preload/index.tsindex 6d43b06..c832d97 100644--- a/src/preload/index.ts+++ b/src/preload/index.ts@@ -47,6 +47,9 @@ const plexoApi = {startDownload: (request: StartDownloadRequest): Promise<string> =>ipcRenderer.invoke(IpcChannels.startDownload, request),+ getCurrentDownload: (): Promise<DownloadState | null> =>+ ipcRenderer.invoke(IpcChannels.getCurrentDownload),+pauseDownload: (downloadId: string): Promise<void> =>ipcRenderer.invoke(IpcChannels.pauseDownload, downloadId),diff --git a/src/renderer/src/hooks/useDownloadEvents.ts b/src/renderer/src/hooks/useDownloadEvents.tsindex 1f5ebe4..1d3e4bf 100644--- a/src/renderer/src/hooks/useDownloadEvents.ts+++ b/src/renderer/src/hooks/useDownloadEvents.ts@@ -6,6 +6,19 @@ export function useDownloadEvents(): void {const setCurrentDownload = useAppStore((store) => store.setCurrentDownload)useEffect(() => {- return window.plexo.onDownloadUpdated(setCurrentDownload)+ let disposed = false+ const unsubscribe = window.plexo.onDownloadUpdated(setCurrentDownload)++ void window.plexo+ .getCurrentDownload()+ .then((download) => {+ if (!disposed && download) setCurrentDownload(download)+ })+ .catch(() => {})++ return () => {+ disposed = true+ unsubscribe()+ }}, [setCurrentDownload])}diff --git a/src/shared/ipc-channels.ts b/src/shared/ipc-channels.tsindex 6593480..6cc9903 100644--- a/src/shared/ipc-channels.ts+++ b/src/shared/ipc-channels.ts@@ -10,6 +10,7 @@ export const IpcChannels = {readClipboardText: 'clipboard:read-text',revealInFolder: 'shell:reveal-in-folder',startDownload: 'download:start',+ getCurrentDownload: 'download:get-current',pauseDownload: 'download:pause',resumeDownload: 'download:resume',cancelDownload: 'download:cancel',