Skip to content

armgit / plexo

Public Imported from GitHub
0

Speed up downloads by combining multiple network connections in parallel

fix: persist downloads across relaunches

HiteshRohirae56fbcf3738e
diff --git a/README.md b/README.md
index 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.ts
index 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: boolean
blocks: 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.initialization
const 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 = undefined
if (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()) return
if (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.ts
index 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 = null
let downloadManager: DownloadManager | null = null
+let quitAfterSuspending = false
function 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.ts
index 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.net
export 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): Down
manager.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.ts
index 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.ts
index 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.ts
index 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',